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1. 



INTRODUCTION 



As the authors of this course, we have made some assumptions 
about your background and why you will be taking this course. 
As the readers, you undoubtedly would like to know what you 
are getting into and what you will get out of it. This chapter 
describes our assumptions and should help you set your 
expectations. It also describes the course structure and 
reference documentation, how to get started, how to get help, 
how to report problems, and how to have your suggestions 
incorporated into future editions of this manual. 



1.1 If you won't write ViewPoint applications 



If you do not intend to write ViewPoint applications we assume 
the following about you: 

• You have Mesa programming experience but little if any 
knowledge of ViewPoint application development. 

• You want an understanding of the principal components of 
a typical ViewPoint application and how they interact. 

We assume that you know how to read Mesa code. 

This manual is intended for programmers. If you are an 
experienced Mesa programmer reading this manual to get the 
flavor of Viewpoint application programming, all well and 
good. If you are not an experienced Mesa programmer and do 
not intend to do any programming exercises, be warned: the 
material is dense and you are not properly dressed for the 
terrain. 



1 .2 If you will write ViewPoint applications 



If you want to develop ViewPoint applications we assume the 
following about you: 

• Your knowledge of ViewPoint application programming is 
limited and you want to expand it to the point that you can 
write significant ViewPoint applications. 

• You are familiar with the Xerox Development Environment 
(XDE). 

• You can program in Mesa. We assume that, at a minimum, 
you have worked through at least the first ten chapters of 
the Mesa Course (see Section 1.6). Nothing in this course 
depends directly on the Mesa Course, however, so you are 
free to acquire expertise in Mesa in other ways. 
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1 .3 Your investment 



You can read the text of this manual in two days. 

We estimate that it will take between three to eight weeks of 
full time study to complete all readings and associated 
exercises. 



1 .4 What you get out of it 



Whether or not you intend to program in Viewpoint, you will 
acquire an appreciation of the architecture of a typical 
Viewpoint application. 

If you complete the course and its associated exercises, you will 
be able to write significant Viewpoint applications, and you 
will know where to look for information on more advanced 
topics. 



1.5 Course structure 



The course has 18 chapters and 3 appendices. This is the first 
chapter. The second chapter discusses the user interface. The 
remaining chapters discuss how to create a new application, 
starting with the basics and gradually increasing in complexity. 
Each chapter concentrates on a particular topic, providing a 
description and examples to illustrate the topic. You should 
work through the chapters in order. 

Each chapter also has an associated programming exercise. 
Some of the exercises build on one another, although we have 
tried to keep them largely independent. We expect that those 
of you who intend to develop Viewpoint applications will do 
all of the exercises. The exercises vary in complexity and 
difficulty; the easiest can be done in a matter of hours, the 
hardest may take as long as a week. We provide solutions to all 
of the exercises. 

The appendices contain information that you need to know, 
but that is not directly part of this course. 

Appendix A, Programming in ViewPoint, describes the logistics 
of writing, testing, and debugging a ViewPoint application. If 
you don't already know how to do this, you should read 
Appendix A immediately after you read this introduction. 

Appendix B, Icon Editor, and Appendix C, Message Tools, 
describe how to use some ViewPoint applications that you may 
need to use in the final chapters. The course text directs you to 
these appendices at the appropriate point. There are no 
exercises associated with the appendices. 
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1 .6 Reference documentation 



The goal of this course is to familiarize you with the basic 
structure of a Viewpoint application and get you started; it is 
not a reference manual, and it does not replace the existing 
reference manuals. Here is a list of other documentation that 
you may need to use before, during, or after the course. 

DF Software Reference Manual 

This describes how to use the df software to simplify 
storing and retrieving large numbers of files. You may 
need to consult this manual to find out how to use the df 
files to retrieve the course software. (See the next section.) 

Mesa Course (version 12.0, July, 1985) 

This is a programming course that covers the Mesa 
language and programming for XDE. 

Mesa Language Manual (version 3.0, November 1984) 

This is the reference for the Mesa programming language. 

Services Programmer's Manual 

This manual contains individual reference manuals for 
Services interfaces. In particular, you will need the Filing 
Programmer's Manual, (November, 1984), which 
documents the Viewpoint filing system. 

Viewpoint Programmer's Gu/de (September, 1985) 

This is a complete reference for Viewpoint programming. 
It describes all procedures in the public ViewPoint 
interfaces. This course is basically a condensed version of 
the information in this manual. This is the primary 
reference for the course. 

Viewpoint Series Reference Library 

This is the set of user manuals for ViewPoint applications 
software. It contains information on documents, folders, 
and the like. 

XDE Tutorials (September, 1 985) 

This is a printed version of the on-line tutorials. 

XDE User Guide (version 3.0, November 1984) 

This is the user manual for the develoment environment. It 
discusses the XDE user interface, and the tools that run in 
XDE. 



1 .7 Setting up your machine 



This section describes how you should set up your machine. In 
most cases, you should show this section to an experienced user 
and let him or her set up your machine for you. 

We assume that you have a Dandelion or Daybreak running 
the XDE 4.0 (or later), and ViewPoint 1.0 (or later). Your 
volume configuration isn't critical, but you should have at least 
a CoPilot volume and a ViewPoint (aka User) volume. 
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Your machine should have the SystemFolder application, and a 
WorkstationProfile with the following two entries: 

[Application Loader] 
Developer: true 

[System] 
Developer: true 

You should also check your user.cm file, which lives on your 
CoPilot volume. The only section that will affect this course is 
the [Executive] section. In particular, you need to check your 
ClientVolume, CompilerSwitches, BinderSwitches, and 
ClientSwitches entries. Here is one possible [Executive] section: 

[Executive] 

CompilerSwitches: eub-j 
BinderSwitches: ec 
ClientVolume: User 
ClientSwitches: Ody\365 

The files that you will need for the course are stored on 
[Bob:OSBU North:Xerox]<\/iewPointProgrammingCourse>. 
Figure 1.1 illustrates the structure within this drawer. 



Viewpoint Programming Course 



12.0 



Exercises Interpress DP Solutions Errata 

(PUBLIC) (PUBLIC, (PUBLIC) (PRIVATE, (PUBLIC) 

Initiaiiy) initially) 



Figure 1.1: The course directory structure 



The Exercises folder contains the files that you will need to do 
the exercises at the end of each chapter. This folder contains a 
folder for each chapter in the course. 

The Interpress folder contains interpress masters for each 
chapter of the course. You can print a copy of the course from 
these if you must, but we recommend that you do not overload 
your printer. Double sided, printed, bound copies of this course 
are available from: 
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Patience Nason 
XDE Technical Services 
Xerox Corporation 
475 Oaicmead Parkway 
Sunnyvale, CA., 94086 
There is a charge for the manual. 

The DF folder contains df files for each chapter in the course. 
You can use these files to retrieve everything you need to do 
the exercises for a given chapter. To find out how to use these, 
consult the DF Software Reference Manual. 

The Solutions folder contains our solutions to the 
programming exercises. 

The Errata folder contains a description of the mistakes that we 
have found since the last printing. 



1 .8 Getting help and reporting problems 



This is the first edition of this course, and we expect that you 
will find some problems and have some suggestions for 
improvements. If you do, we would appreciate it if you would 
report them. Internal users can submit ARs against the course 
(System Documentation:OSBU South, subsystem Programming 
Course); external users can send mail messages to the 
distribution list XDESupport.osbunorth@Xerox.COM. 



1.9 Future editions 



If you have suggestions about topics that you would like to see 
included in future editions, we would like to hear from you. If 
you have written Viewpoint applications that are elegant, 
relevant, and reasonably compact and would like to see them 
immortalized in subsequent editions, please submit them to us 
for review. You can contact the authors through the 
distribution list XDE-Training:osbu north:Xerox if you are an 
internal user or XDE-Training.osbunorth@Xerox.COM 
otherwise. 
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Notes: 
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USER INTERFACE 



This chapter describes the ViewPoint user interface, which is 
based on the metaphor of a business office. The user interface 
includes symbols for standard components of an office, such as 
the desktop, folders, file drawers, baskets for incoming and 
outgoing mail, and wastebaskets. 

Viewpoint also provides programming interfaces to support 
these user interface characteristics. By using these interfaces 
when you write new applications, you ensure that your 
applications integrate well with existing software. This chapter 
describes the basic components of the user interface; the rest 
of this course describes how to incorporate these user interface 
features into a new application. 



2.1 The Desktop and icons 



The Viewpoint user interface is based on the idea of icons that 
reside on a desktop. The desktop represents the typical 
business office; an icon represents an object in that office. A 
typical desktop might include icons that represent various 
documents, folders, mail baskets, a printer, and so on. 

The user accesses an object through its icon, generally by 
selecting the icon and pressing the open key. The move, copy, 
and DELETE keys also apply to icons. Figure 2.1 illustrates a 
desktop with several different icons and an open document. 




Figure 2. 1 : Icons on a desktop 
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The user can move the icons to different positions on the 
surface, but two icons cannot occupy the same square at the 
same time. 

The use of icons is simple and intuitive. Therefore, you should 
use icons to represent applications that the end user will access 
frequently. However, since associating an icon with an 
application requires a fair amount of programming overhead 
and the icon itself uses screen real estate, icons are not a cost- 
effective or efficient way of representing simple, infrequently 
used applications. Instead, you can have such applications run 
from a command in a global pop-up menu, as described in the 
next section. 



2.2 Windows 



A window is a rectangular region of the display screen in which 
an application can display information to the user. Figure 2.2 
illustrates the various parts of a basic window. 



Control point 



Header 



Commands 



Control point 



Control point 



TM 




Pop-up menu with 
additional commands 



Window 
manager 



Document menu 



Vertical 
Scrollbar 



Horizontal 
Scrollbar 



Control point 



Figure 2.2: A basic window 
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Windows can be in one of two modes: overlapping or tiled. In 
overlapping mode, windows can appear on top of each other 
and there is no limit to the number of windows that can 
appear. In tiled mode, each window occupies its own section of 
the screen, and there is no overlap. Windows must be in one 
mode or the other; you cannot have some windows in 
overlapping mode and others in tiled mode. 

Initially, windows are in overlapping mode: each window has a 
single-line header and a control point in each corner. Pressing 
POINT (the left mouse button) in any control point invokes a 
Top/Bottom operation. Pressing point down in any control 
point and then moving the mouse moves the entire window. 
Pressing adjust (the right mouse button) in any control point 
and then moving the mouse changes the size of the window. 

You can specify whether overlapping windows employ simple 
offset, repeat offset, or don't offset. Simple offset means that 
up to six windows can appear at one time, starting at the upper 
left and going to the lower right. The seventh window appears 
on top of the first window and the same pattern continues for 
each succeeding window. If you close a window and then re- 
open it, the system remembers the window's initial position 
and redisplays it in that position. Repeat offset opens windows 
in the same way as simple offset. However, if you close and 
then reopen a window, the system does not remember the 
initial location of the window, but rather places it in the first 
available position. With don't Offset, there is no rigid 
ordering; windows can appear anywhere on the screen. 

When windows are in tiled mode, no more than six windows 
can appear on the screen at one time. You cannot move a tiled 
window on top of another tiled window. You can only move it 
to an empty space on the screen. 

To switch between overlapping and tiled mode and between 
simple, repeat, and don't offset, you can either use the 
Window Management property sheet or edit the User Profile. 
The Window Management property sheet is available through 
the Attention Window menu; it specifies whether windows 
appear overlapping or tiled and with single- or double-line 
headers. (The next section discusses the Attention Menu.) 

If you want to change the defaults for these parameters, you 
can edit the User Profile. (For more information on the User 
Profile, consult the ViewPoint user documentation.) Here is an 
example of a User Profile entry for window characteristics: 

[Windows] 

Arrangement: overlapping -or tiled 

Header Style: single line - or double line 

Placement: simple offset ~ or repeat or don't offset 



2.3 Pop-up menus 



A menu is a list of named commands. A pop-up menu is a menu 
that appears only when the user specifically requests it by 
holding down the left mouse button over the pop-up menu 
symbol ( = ). Each application generally has a pop-up menu; the 
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author of the application chooses which commands go directly 
in the window header and which go in the pop-up menu. 
However, if the window is too small for all the specified 
commands to fit in the header, the rightmost header 
commands will automatically overflow into the pop-up menu 
instead of appearing in the header. Using pop-up menus 
conserves screen space while the menus are not in use, but 
means that the commands are not readily visible and that the 
user must go through an extra step to access a command. 



2.4 Attention window 



The Attention window is the window that appears across the 
top of your screen. The Attention window has an associated 
pop-up menu with a list of system-wide commands; you can 
access the menu by mousing anywhere in the Attention 
window, not necessarily over the menu symbol itself. The 
Attention window also allows applications to display messages 
to the user. Figure 2.3 illustrates the Attention window and its 
associated menu. (The Attention window is also shown in 
Figure 2.1.) 



Attention 
window 



Attention 
window 
with menu 
shown 





Date and time 
End session 
Show User Profile 
Show Size 
Spelling Checker 
Paginate 




Please confirm the command 











Figure 2.3: Attention window 



You can access a standard set of commands available from the 
Attention menu, and applications can add commands to this 
menu. For example, many applications run from a command in 
the Attention window menu rather than from an icon. Thus, 
when the user wants an application's window to appear, he 
invokes the appropriate command from the Attention window 
menu, instead of selecting an icon and opening it. As a 
programmer, you get to choose whether your application runs 
from an icon or from a command in the Attention window. 
Placing commands in the Attention Window menu conserves 
screen space, but makes them less accessible than icons. 



2.5 Form windows and property sheets 



A form window is a window that displays one or more items. 
There are many types of items, the most common of which are 
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boolean, choice (enumerated), and text. The user can observe 
the current value of each item in the form and change that 
value if he desires. Figure 2.4 illustrates a form window for a 
calendar application. 




Figure 2.4: Sample Form window 



A property sheet is a form window in which the items control 
the properties of an object. To see the properties of an object, 
select the object and then press the props key. Different objects 
have different properties; for example, the properties of a 
paragraph include left and right margins, justification, and line 
height. The header of a property sheet usually contains some 
subset of the standard commands: ? (Help), Done, Cancel, 
Apply, and Defaults. Figure 2.5 illustrates a property sheet for 
the Wastebasket icon. 



r;j^-^^YE B A S 1^^^^^^ E RT I E S ^^^^^^H^W 6 o e ¥ ^ a ^^^^^^^^^^^ 



Purge deleted item: 



IMMEDIATELY 



NEVER 



Number of contained items ; 24 



Total 5ize:1 027 Disk Pages 



+ 



Figure 2.5: Property sheet for the Wastebasket icon 
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2.6 The Directory icon 



Every ViewPoint desktop has a Directory icon, which provides 
access to various ViewPoint applications and features. Opening 
the Directory icon provides three choices: Worl<station, User, 
and Network. The Workstation category contains workstation- 
specific items, such as blank documents, the Converter, and the 
Loader. The User category contains user-specific items, such as 
mail in and out baskets, a wastebasket, and the User Profile. 
The Network category provides access to icons for remote 
servers, such as printers and file drawers. You can copy icons 
out of the Directory as needed. 



2.7 The Prototype folder 



When you run an application that has an icon, the icon does 
not automatically appear on the desktop. Instead, you must 
open a special system folder, known as the Prototype Folder, 
selected the desired icon, and copy it to the desktop . Figure 2.6 
illustrates the Prototype folder. 



Name Version 
r~*) Basic Graphics Transfer Document 
Q Blank Document 
Blank Folder 
Blank Mail Folder 
Blank Mail Note 
Blank Reference 



□ 



Date 



IH 



Figure 2.6 Prototype folder 



There are two possible ways to access the Prototype folder. The 
first method is to open the Directory Icon and then the 
Workstation folder. Inside the Workstation folder is a folder 
called Basic Icons; this Is the Prototype folder. Inside this folder, 
you will find such icons associated with the various applications 
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running on your machine; you can copy any or all of these 
icons to your desktop. 

The second way to access the Prototype folder is a shortcut, but 
it requires that you be running the program SystemFoider.bcd. 
(The easiest way to run this program is to drop it on the Loader 
directly from a file drawer; see Appendix A, Programming In 
Viewpoint, for more information on running a program.) 

System Folder registers three commands in the Attention IVIenu, 
one of which is Prototype Folder. Selecting this command will 
open the Prototype folder on your screen. (The other 
commands are System Folder, and Set System Folder Filter. See 
Appendix A, Programming In ViewPoint, for more information 
on these commands.) 



2.8 Other user interface features 



This chapter discussed the major user interface features that 
you might want to incorproate into a new application. For a 
complete discussion of the ViewPoint user interface from the 
user's point of view, however, you should refer to the 
Viewpoint Series Reference Library and the ViewPoint Series 
Training Guides. 
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Notes: 
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STRINGS AND 
MESSAGES 



This chapter discusses some basic aspects of Viewpoint 
programming, such as string representation, manipulation, 
and management. 

The specific interfaces covered are XChar, which defines the 
structure of a character; XString, which defines the structure of 
a string and various operations on strings; XFormat, which 
supports conversion among various data types; XMessage, 
which helps separate messages to the user from the rest of the 
code for an application; and Attention, which supports posting 
messages to the user. 

The material in this chapter is difficult, but it is necessary 
background to the rest of the course. 



3.1 XChar 



Most computer systems represent characters with either a 7-bit 
code (ASCII), or an 8-bit code (ISO). An 8-bit code allows 256 
characters, which is plenty for English and associated special 
characters, but not nearly enough for multilingual capability. 
To allow true multinationality, character codes need to be 
much bigger, which has obvious attendant disadvantages. 

The Xerox solution to this problem is a character encoding 
system (The Xerox Character Code Standard) that normally 
conforms to the ASCII and ISO 8-bit character codes, but 
expands to a 16-bit code when necessary. Defining a character 
as 16 bits provides 65,536 distinct characters; reserving space 
for control characters reduces it to 65,512 . This 65,512 range is 
partitioned into 256 blocks {character sets) of 256 character 
codes each. (Actually, there can be at most 255 x 255 
characters; the last block is reserved.) 

A character is thus composed of two 8-bit quantities: a 
character set and a character code. The character set is optional 
when all characters in a given string are part of the same 
character set. When there is no character set, the character 
code conforms to ASCII and ISO. This approach provides both 
versatility and compactness. 

The XChar interface defines the basic character type and some 
operations on that character type. 

xchar.Character: type = word; 

xchar.CharRep: TYPE = machine dependent record [ 
set, code: Environment.Byte]; 
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3.2 XString 



The XString interface provides data structures and operations 
for strings encoded with the Character Code Standard. XString 
declares two l<inds of strings: one for read-only access 
("reader") and one for writing ("writer".) Readers occupy less 
space than writers. Thus, programs that create strings once and 
do not later need to modify them can save significant space. 



3.2.1 Readers and ReaderBodys 



XString defines the following types for readers: 



xstring.Reader: TYPE ■ long pointer to xstring.ReaderBody; 

xstring.ReaderBody: TYPE s private machine dependent record[ 
context(O): xstring.Context, 
limit(1): cardinal, 
offset(2): cardinal, 
bytes(3): xstring.ReadOnlyBytes]; 

xstring.Context: type ■ MACHINE DEPENDENT record [ 

suff ixSize(0:0..6): [1 ..2], -bit positions 0-6 in word 0 
homogeneous(0:7..7): boolean, 
prefix(0:8..T5): xstnng.Byte]; 



xstring.ReadOnlyBytes: type s 

long POINTER TO readonly xstring..ByteSequence; 



xstring-ByteSequence: TYPE = record [ 

PACKED sequence COMPUTED CARDINAL OF XString. Byte],' 



XString. Byte: TYPE ■ Environment. Byte; 



The basic structure is the sequence referenced by bytes, limit is 
the offset from the pointer to the byte after the last byte in the 
byte sequence; and offset is the offset from the pointer to the 
first byte (the "beginning" of the string). Figure 3.1 shows two 
ReaderBodys, one that starts at the beginning of the byte 
sequence (offset = 0), and one that starts in the middle of the 
byte sequence (offset * 0.) 



offset = 0 

limit = (3-0) +1 = 4 



bytes 



offset = 2 

limit = (10-2) + 1 = 9 
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bytes 
\ 0 1 
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Figure 3.1 : xstring.ReaderBody 
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A Context contains information about the character encoding 
within the byte sequence. The suffixSize field describes 
whether the first byte is encoded as a 8-bit character or a 1 6-bit 
character. The homogeneous field is an accelerator specifying 
whether the byte sequence contains any character set shifts. 
The prefix field specifies the character set of the first character. 
Subsequent characters in the string use the same prefix unless 
there is an encoding transition. (The prefix field is used only for 
8-bit characters, since the 16-bit representation includes a 
character set.) 

Figure 3.2 illustrates these data structures. 



Reader 



context 



suffixSize 

homogeneous 

prefix 



(7 bits) 
(1 bit) 
(8 bits) 




►context 



limit 



offset 



bytes 



ReaderBody 

offset: the offset from the pointer to the first byte 

limit: the offset from the pointer to the byte after the last 
byte in the byte sequence 

context: describes how characters are encoded 

suffixSize: states whether the first character is 
encoded in 8 bits or 16 bits 



contains the character set of the first 
character (only for 8-bit characters) 



prefix: 

homogeneous: true if no character set shifts in sequence 




Figure 3.2: Reader and ReaderBody 



Examples of character encodings and character set shifts are 
beyond the scope of this course; if you are interested, consult 
the XChar chapter of the Viewpoint Programmer's Manual, the 
Xerox Character Code Standard, or the Xerox NetworkSytems 
Architecture General Information Manual. 
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3.2.1 .1 Accessing the contents of a reader 



Because of the possibility of different character encodings, you 
shouldn't access the contents of a reader just by indexing. 
Instead, you should always use procedures from the XString 
interface. For example: 

XString.Flrst: PROCEDURE [r: XString.Reader] RETURNS [ 

c: xstring.Character]; 

xstring.NthCharacter: procedure [r: xstring.Reader, n: cardinal] 
RETURNS [c: xstring.Character]; 

XString.Lop: PROCEDURE [r: XString.Reader] RETURNS [ 

c: xstring.Character]; 

First and NthChar return the specified character; Lop removes 
the first character and returns it. First and Lop are more 
efficient than NthCharacter; you should use them when 
appropriate. XString also provides procedures to determine 
other information about a reader, such as the number of 
logical characters that it contains; consult the XString chapter 
of the Viewpoint Programmer's Manual for details. 

3.2.1.2 Creating readers 



There are several ways to create readers. One way is to start 
with a writer; once the contents are fixed, you can use 
xstring.ReaderFromWrlter to convert from a writer to a reader. 
You can also use xstring.FromSTRING or xstring.FromNSString to 
convert a Mesa string or an NSString into a reader: 

xstring.ReaderFromWrlter: procedure [w: xstring.Writer] 

RETURNS [xstring.Reader] B INLINE ... ; 

xstring.FromSTRING: procedure [s: long string, 
homogeneous: boolean false] 
returns [xstring.ReaderBody]; 

xstring.FromNSString: procedure [s: NSString.String, 
homogeneous: boolean false] 
RETURNS [xstring.ReaderBody]; 

3.2.1 .3 Readers vs. ReaderBodys 



When writing procedures and data structures, you must decide 
when to use the actual ReaderBody or just the Reader. 
Obviously, since readers are just pointers, they require less 
space than ReaderBodys. However, you should use the 
ReaderBody when keeping track of who owns the storage is a 
problem. Thus, you should generally put a ReaderBody, not 
just a Reader, in your data structure. 

For procedures, the guideline is to take a Reader and return a 
ReaderBody. The idea is that passing readers as parameters 
reduces the number of words of parameters, while returning 
ReaderBodys allows the client to manage the storage for the 
ReaderBody. 
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Another guideline is that clients should be able to pass pointers 
to local ReaderBodys. That is, clients should be able to allocate 
ReaderBodies from the local frame, rather than from 
permanent storage. For example, consider the following 
fictional procedure that renames a file: 

RenameFlle: PROCEDURE [oldName:xstring. Reader] a { 
rb: xstring.ReaderBody <-Someinterface.GetNewName[] ; 
file <-Someinterface.LookupByName[oldName]; 
someinterface.Rename[file: file, newName: @rb]}; 

The procedure RenameFile takes a reader, which it passes to 
LookupByName. This is an example of using a reader as a 
parameter. GetNewName, on the other hand, returns a 
ReaderBody. If it returned a Reader, there would be a problem 
with the storage for the ReaderBody. Either it would have to 
be global, or it would have to be deallocated from a known 
place after RenameFile was done with it. Returning the 
ReaderBody itself makes it clear that RenameFile owns that 
storage and can deallocate it when appropriate. The newName 
parameter to the Rename operation is a pointer to a local 
ReaderBody. Rename should copy the ReaderBody (and the 
bytes) if it i ntends to save the characters. 



3.2.2 Writers and WriterBodys 



A Writer is much like a Reader, except that it has additional 
fields to permit editing: 

xstring.Writer: TYPE a LONG POINTER TO xstring.WriterBody; 

xstring.WriterBody: TYPE = private machine dependent record [ 
context(O): xstring.Context, 
limit(1): cardinal, 
offset(2): cardinal, 
bytes(3): Bytes, 
maxLimit(5): cardinal, 
endContext(6): xstring.Context, 
zone(7): uncounted zone]; 

xstring.Bytes: TYPE a LONG POINTER TO xstring.ByteSequence; 

The first four fields are the same as in a reader; the last three 
fields contain information to support editing. maxLimit 
describes the limits of the allocation unit; endContext is the 
context that describes the encoding of the last character (this is 
an accelerator for operations that append characters); and 
zone is the zone that contains the allocation unit. 

Including a zone in the WriterBody enables operations that 
add characters to the writer to allocate a larger byte sequence, 
copy the old bytes, and update the byte pointer in the 
WriterBody without invalidating the caller's writer variable. 

3.2.2.1 Allocating writers 



There are several ways to initially create a writer. To allocate a 
brand new writer, call xstrlng.NewWriterBody: 
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xstring.NewWriterBody: procedure [maxLength: cardinal, 

z: UNCOUNTED zone] 

RETURNS [xstring.WriterBody]; 

NewWriterBody allocates a byte sequence that has room for 
maxLength bytes using z and returns an empty WriterBody 
that contai ns the bytes. 

You can also create writers from existing strings or NSStrings: 

xstring.WriterBodyFromNSString: procedure [ 
s: NSString.String, 
homogeneous: boolean <- false] 
returns [xstring. WriterBody]; 

xstring.WrlterBodyFromSTRING: procedure [ 

S: LONG STRING, 

homogeneous: boolean false] 
RETURNS [xstring. WriterBody]; 

3.2.2.2 Expanding writers 



You can expand a WriterBody with xstring. ExpandWriter: 
xstring.ExpandWriter: procedure [w: xstring.Writer, extra: 

CARDINAL]; 

ExpandWriter assures that at least extra bytes are available in 
the writer's bytes. There are several procedures for writing and 
editing writers; check the Viewpoint Programmer's Manual to 
find out what is available. 

3.2.2.3 Editing writers 



There are a number of procedures that you can use to add 
information to a writer or to edit a writer. For example, there is 
a procedure to add a reader to a writer (xstring.AppendReader), 
to add a character to a writer (xstring.AppendChar), to append 
a mesa string to a writer (xstring.AppendSTRING), and so on. 
See the Viewpoint Programmer's Manual for the declarations 
of these procedures. 

Another common way to add contents to a writer is with the 
XFormat interface, as described in the next section. 



3.3 XFormat 



The XFormat interface provides facilities for formatting data 
types into other data types. For example, you could use 
XFormat to convert a series of characters into an XString, or a 
series of cardinals into an NSString. Instead of providing a 
different routine for every possible conversion that you might 
want to do, however, the XFormat interface provides a 
standardized way of converting one type to another. 

The basic idea is to convert the input data to an intermediate 
format, and then convert from that intermediate format into a 
specified output format. (The intermediate format is just a 
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Reader, but you don't need to know that to use the XFormat 
facilities.) Figure 3.3 illustrates this idea. 



Object to be formatted 




r 


Format abstraction 
(Format Proc) 




r 


Destination (sink) 



Figure 3.3: The XFormat abstraction 

The major data structure of the XFormat interface is the 
Handle: 

XFormat.Handle: TYPE a LONG POINTER TO XFormat.Object; 

xFormat.Object: type = record [ 
proc: XFormat.FormatProc, 
context: xstring.Context <-xstring.VanillaContext, 
data: XFormatClientData ^nil]; 

XFormat.FormatProc: type ■ procedure [r:xstring. Reader, 
h: XFormatHandle]; 

XFormat.CllentData: TYPE ■ long pointer; 

A handle is a pointer to an Object; the principle field of an 
Object is the format procedure, proc. The format procedure is 
responsible for converting from the intermediate format 
(reader) to the output format. It takes a reader and a handle as 
parameters, and it should pass its reader parameter to its 
output sink. Obviously, there must be a different format 
procedure for every type of output; a format procedure that 
produces streams is not the same as a format procedure that 
produces writers. 

The context field of an Object contains context information on 
the last character sent to the format procedure; the format 
procedure is repsonsible for updating this information. 

To use the XFormat facilities, the first step is to create an Object 
that has a format procedure that implements the output sink 
you are interested in. For example, you might want to use a 
writer or a stream as your output sink. You can then pass in 
various data types that you want to add to the writer, as 
illustrated in Figure 3.4. Note that you can either pass several 
items invididually to several different writers, or you can 
concatenate them into one writer. 
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Figure 3.4: Using a writer as output sink 



The XFormat interface provides format procedures for four 
common data types: xstring.Writer, stream. Handle, TTY.Handle, 
and NSString. String. Thus, if you want to use any of these four 
data types as your output sink, then you don't have to write 
the procedure that converts from a reader to your specified 
output format. If you want to use an output sink other than 
these four, then you do need to write the procedure yourself. 

For example, suppose that you want to use a stream as your 
output sink. (For now, don't worry about it if you don't know 
what a stream is; we discuss streams at length in Chapter 12, 
Streams. For now, you just need to get a basic idea of how 
XFormat works.) You can make a call to the procedure 
XFormat.StreamObject, which will create an Object with the 
correct format procedure, and with the stream as its data 
parameter. 

The format procedure itself is called XFormat.StreamProc: 
XFormat.StreamProc: XFormat.FormatProc; 



XFormat.StreamObject: procedure [sH: stream. Handle] 

RETURNS [XFormat.Object]; 



Figure 3.5 illustrates the format object that StreamObject 
returns. 



FormatObject 



proc: XFormat.StreamProc 
context: XFormat.VanillaContext 
data: sH 



Figure 3.5: An XFormat.Object with a stream as 
output sink 
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Once you have initialized the format object, you can then pass 
in the data that you want to format. XFormat provides a 
number of procedures that you can call to pass various data 
types to a format object. For example: 

XFormat.Char: procedure [h: xFormat.Handle «-nil, 
char: xstring.Character]; 

XFormatDecimal: proedure [h: XFormat.Handle <-nil, 
n: LONG integer]; 

XFormat-Reader: proedure [h: xFormat.Handle <- nil, 
r: xstring.Reader]; 

These procedures all take two parameters, a piece of data of 
the specified type, and a Handle. They take the piece of data, 
format it into a reader, and then pass it to the format 
procedure in the format object, which formats it into the 
desired output format. 

Here is an example that concatenates several different data 
types into a writer: 

-Statementi : create a new writer 
writerBody: xstring.WriterBody <- 

xstring.NewWriterBody[maxLength:250, z: sysZ]; 
StatementZ: Create an object with writer format object 
xfo: XFormat.Object «-XFormat.WriterOb]ect[ 

w: @writerBody]; 
Statements: Concatenate data types into writer 
XForniat.String[h:@xfo,s:"My name is "L]; 
XFormat.Stri ng[ h : @xf o, s : na mePassedl n AsAPa rameter] ; 
XFormat. String[h:@xfo, s:" and my age is "Ll; 
XFormat.Decimal[h:@xfo, n: agePassedlnAsAParameter]; 
XFormat.Char[h:@xfo, char: '..ORD]; 

This example first creates a new writer, and then calls 
WriterObject to create an object initialized with the format 
procedure WriterProc and data ©writerBody. This sets up the 
writer as the output sink, as illustrated in the innermost box of 
Figure 3.6. 

The next step is to call String, Decimal, and Char to put the 
various data types to the writer. Each of these procedures takes 
a piece of data, puts it in the intermediate format, and then 
calls h.proc, passing in the data. Thus, String calls h.proc, 
(which is the writer format procedure WriterProc), passing in 
the string "My name is,", and WriterProc puts the bytes of the 
string to the writer. Note that the argument to Char is just a 
period; the statement above takes the ordinal value of the 
period character. 

This code will create a writer whose contents are something 
like this: "My name is Lucille and my age is 11." 
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Data structures after executing Statement 2 



Data structures after executing Statement 1 
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Figure 3.6: Diagram of XFormat example 



For the purposes of this course, you do not need to see the 
actual code for a format procedure. It you want to write your 
own format procedure for a data type other than the four that 
XFormat supports, see the XFormat chapter of the ViewPoint 
Programmer's Manual. 



3.4 XMessage 



The idea behind the XMessage interface is to group all 
messages that the user sees (generally speaking, all the readers 
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in a program) into a single module. Eventually, when you are 
through with your application, you can use Message Tools to 
remove the messages from the code altogether. The advantage 
of this approach is that you can change the messages without 
changing the code; this is particularly important when dealing 
with multinational applications. 

During development, however, while things are still changing, 
you should use the method described here. Chapter 16, 
Application Folders and Appendix C, Message Tools describe 
how to handle messages for a completed application. 

The messages mechanism used during develoment uses the 
standard three-module structure: a definitions module, an 
implementation module, and one or more client modules. 



3.4.1 The definitions module 



The definitions module defines the messages for the 
application and a procedure for clients to call when they need 
to access the messages. (A message definitions module does 
not have to be distinct from other interfaces; you can just add 
the messages definitions to another interface, if you like.) 

First, you need to define a type Key that includes a name for 
each of the messages. Thus, for example: 

Key: TYPE a {hlMom, elephant, noFlie, badlnput}; 

You also need a procedure that clients can call to access the 
messages. For example: 

Get: pROc[key: Key] returns [xstring.ReaderBody]; 

The job of this procedure is to return the actual message 
corresponding to the specified key. 



3.4.2 The implennentdtion module 



The second piece is the implementation module that supplies 
the actual messages. In the implementation module, you need 
to define the actual text for each message, and implement the 
Get procedure. 

The first step is to call XMes$age.AllocateMessages, which 
defines the domain of messages for your application: 

XMessage.AllocateMessages: procedure [ 
applicationName: long string, 
maxMsglndex: cardinal, 
cl lentData : xMessage.CI lentData, 
proc: XMessage.DestroyMsgsProc] 
RETURNS [h: XMessage. Handle]; 

XMessage.Handle: type a LONG POINTER TO XMessage. Object; 

XMessage.Object: TYPE; 
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applicationName is the name of the application, maxMsglndex 
is the number of messages, clientData is for your own use. 
DeleteMessages is a call back procedure to deallocate any 
storage associated with the message handle. 

AllocateMessages returns a message handle for the 
application; here is an example of calling this procedure: 

h: XMessage.Handle f-XMessage.AllocateMessages [ 
applicationName: "TestApplication"U 
maxMessages: MsgDefs.MessageKey.LAST.ORD + 1, 
clientData: nil, 
proc: nil]; 

To implement the messages, you need to create an object of 
type XMessage.Messages: 

XMessage.Messages: type = 

LONG DESCRIPTOR FOR ARRAY OF XMessage.MsgEntry; 

XMessage.MsgEntry: TYPE = RECORD [ 

msgKey : XMessage.MsgKey, -key used in interface 
msg: xstring.ReaderBody, -The actual message 
owner: long string nil, -Who owns the ReaderBody 
severity: XMessage.MsgSeverity <<- good, 
translationNote: long string <- nil, 
translatable: boolean <- true, 
type: XMessage.MsgType <- userMsg, 
id: XMessage.MsgID]; 

XMessage.MsgKey: TYPE ■ CARDINAL; 

msgKey is the ordinal value of the key defined in the interface 
(for example, khiMom), and msg is the actual text for the 
message. The other fields are for the purposes of translation. 
The only one that you must supply is id, which is a unique 
identifier. This id is for the use of the translators and should not 
change; note that the id and the msgKey for a message don't 
have to be the same. 

For example, here is a fragment that illustrates how to 
implement the hiMom key: 

msgArray: array Defs.Key of XMessage.MsgEntry [ 
hiMom: [ 

msgKey: Defs.Key.hlMom.ORD, 

msg:xstrng.FromString["Hi, Mom!"], 

id:1]. 
...]; 

The final step is to call XMessage.RegisterMessages to actually 
initialize your messages: 

XMessage.RegisterMessages: procedure [ 
h: XMessage.Handle, 
messages: XMessage.Messages, 
stringbodiesAreReal: boolean]; 

This procedure takes a message handle and the messages for 
the application, and initializes the messages. If 
stringBodiesAreReal is false, then RegisterMessages will copy 
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the bytes for the string; if it is true, then RegisterMessages 
assumes that the bytes will remain valid. 

Once you have made this call, clients can access your messages 
by calling Get; to implement Get, just call XMessage.Get: 

XMessage.Get: PROCEDURE [ 

h: XMes$age.Handle, msgKey: XMessage.MsgKey] 
RETURNS [msg: xstring.ReaderBody]; 

For example: 

Get: PUBLIC PROCEDURE [key: Defs.Key] returns [xs.ReaderBody] ■ 
RETURN h.Get[key.ORDl}; 

Here is a complete implmentation module: 

DIRECTORY Defs, XMessage, XStHng; 

MsglmpI: program imports XMessage, XString exports Defs s { 
openXS: XString; 

h: XMessage.Handle «- nil; - The messages handle 

Get: PUBLIC PROC [key: Defs.Key] returns [xs.ReaderBody] ■ 
return h.Get[key.ORD]}; 

Init: PROC » { - Creates, allocates, and registers messages 
msgArray : array Defs.Key of XMessage.MsgEntry <- 
[hiMom: [ 

msgKey: Defs.Key.hlMom.ORD, 

msg: XS.FromString["Hi, Mom!"L], 

id:1], 
elephant: [ 

msgKey :Defs.Key.elephant.ORD, 

msg: xstring.FromSTRING ["Elephants are pink."L], 

id: 2], 
noFile: [ 

msgKey:,Defs.Key.noFile.ORD, 

msg: xstring.FromSTRING ["Error.. .file notfound"L], 

id: 3], 
badlnput: [ 

msgKey:Defs.Key.badlnput.ORD, 

msg: xstring.FromSTRING ["Invalid input."L], 

id: 4]]; 

messages: XMessage. Messages descriptor [loophole [ 
msgArray, ARRAY[0..Defs.Key.LAST.ORDl of 
XMessage.MsgEntry]]; 

h <-XMessage.AllocateMessages [ 

a ppl ication Name: "TestAppI icati on " L, 
maxMessages: Defs.Key.LAST.ORD + 1, 
clientData: nil, 
proc:NiL]; 

XMessage. RegisterMessages [ 
h:h, 

messages: messages, 
stringBodiesAreReal: false]}; 

-Mainline code 
Init [];}... 
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3.4.3 The client module 



From the client side, things are much simpler: you just call 
Defs.Get to retrieve a particular message. For example: 

Typical message usage 

noFlle: xstring.ReaderBody <- Defs.Get [Defs.Key.noFile]; 



Attention. Post [@noFllel;}. "Discussed in the next section 

One final note on XMessage: the method we present here is 
slightly different (and simpler) than that suggested in the 
Viewpoint Programmer's Manual. Unfortunately, many of our 
examples either don't use messages or use the other method. 
Do as we say, not as we do. 



3.5 Attention 



The Attention interface implements a single window for 
displaying messages. The Attention Window also has an 
associated menu; Chapter 4, Simple Application, describes this 
menu. 

There are three types of messages that you can put in the 
Attention Window: simple messages, sticky messages and 
confirmed messages. Simple messages have no special 
semantics. Sticky messages are redisplayed when a non-sticky 
message is cleared. Attention keeps track of one sticky 
message. Confirmed messages ask the user to confirm 
something. 

There are three posting operations: Post, PostSticky, and 
PostAndConfirm. 

Attention.Post: PROCEDURE [s: XString.Reader, 

clear: boolean <-true]; 

Attention.PostSticky: PROCEDURE [s: XString.Reader, 
clear: boolean <-true]; 

Attention.PostAndConfirm: procedure [ 
s: XString.Reader, 
clear: BOOLEAN <- true, 

confirmChoices: Attention.ConfirmChoices <-[nil, nil], 
timeout: Process.Ticks <- Attention.dontTimeout] 
RETURNS [confirmed, timedOut: boolean]; 

The Post procedures display the message s in the Attention 
window. If clear is true, the procedure clears the Attention 
window before displaying s, otherwise it displays it after 
whatever text is currently showing. PostAndConfirm acts like 
Post in displaying the message s but waits for the user to 
confirm. See the Viewpoint Programmer's Manual for details 
on how to use PostSticky and PostAndConfirm. There are also 
the inverse operations: 
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Attention.Clear: PROCEDURE; 
Attention.ClearSticky: procedure; 

Clear clears the Attention window of any simple message. If 
there is a current sticky message. Attention will display it after 
clearing the simple message. Clear has no effect if the current 
message is sticky. ClearSticky clears any current sticky message. 
ClearSticky has no effect if there is no sticky message. 

Constructing messages in the single global Attention window 
does not work well if multiple processes try to display messages 
simultaneously. Thus, to avoid interference, you should follow 
this guideline: only call procedures in the Attention interface 
from the Notifier process. Chapter 9, TIP, discusses the Notifier 
process in detail; for now, you should just realize that there is a 
potential conflict. 



3.6 Summary 



The XChar interface provides the definition of a character. 
Viewpoint characters are encoded with the Xerox Character 
Code Standard, which provides increased generality at the 
price of slightly increased complexity. 

The XString interface defines the data structures and opeations 
for strings. XString defines two different kinds of strings, 
readers (read-only strings) and writers (editable strings.) 
XString provides a wide variety of procedures for manipulating 
both readers and writers. 

The XFormat interface provides procedures to format various 
data types into readers, and vice versa. 

The XMessage interface provides facilities for keeping 
messages that the user will see (readers) separate from the 
actual code for the application. To use the XMessage 
approach, you need three modules: a definitions module, a 
client module, and an implementation. 

The Attention interface allows you to post messages to the 
global attention window. The chief procedures are Post and 
Clear. 



3.7 Exercise 



The exercise for this chapter is the Concordance Tool, which 
determines the number of times that a particular pattern 
occurs in a textual selection. To use this tool, you fill in a 
pattern and a selection, specify a context, and then invoke the 
Find All command. (The context is the number of words on 
each side of the pattern; note that the pattern cannot include 
wildcard characters.) The tool then provides a list of matches in 
the specified context, and a count of the total number of 
matches. Figure 3.7 illustrates this tool. 
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Figure3.7 The ConcordanceTool 



Your assignment is to complete the module 
ConcordFormlmplTemplate.mesa. Specifically, you need to 
write the two procedures Find, and ProcessString. Find is the 
Formwindow.CommandProc that implements Find All: it first calls 
a procedure to get the current selection, and then calls 
ProcessString, which searches the text for pattern matches and 
extracts concordances for each match. Find then displays any 
matches and also frees any storage. 



For a complete explanation of what you need to do, see the 
comments in ConcordFormlmplTemplate.mesa. You will also 
need the following modules: 



Concord Defs. bed 
Concord M sg I m pi . bed 
Concordlmpl.bcd 
ConcordSel ection I m pi . bed 
Concord. config 
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This chapter discusses how to create a basic user interface for 
an application: how to add a command to the Attention Menu, 
how to create a window, and how to display the window on 
the screen. The information in this chapter is just a skeleton; 
the next four chapters discuss how to add additional 
functionality and features to your user interface. 



4.1 Adding a command to the Attention menu 



You can structure a Viewpoint application to run either from a 
command in the Attention Menu or from an icon. Chapter 14, 
Icon Applications, discusses how to write applications that use 
icons; this chapter describes how to write an application that 
runs from a command in the Attention Menu. 

To have your application run from the Attention Menu, you 
need to add a command to the menu and supply a procedure 
to implement that command. To add a command to the 
Attention Menu, call Attention-AddMenultem: 

Attention.AddMenultem: procedure [Item: 
MenuData.ltemHandle]; 

MenuData.ltemHandle: TYPE » long pointer to MenuOata.ltem; 

MenuData.ltem: TYPE a MenuData.Privateltem; --hidden 

AddMenultem requires a parameter of type ItemHandle, which 
represents a menu item. To get an ItemHandle, call 
MenuData.Createltem : 

MenuData.Createltem: procedure [ 
zone: uncounted zone, 
name: xstring. Reader, 
proc: MenuData.MenuProc, 
itemData: long unspecified <-0] 
returns [MenuData.ltemhandle]; 

Createltem builds an item record in zone, name is the string 
that will appear in the menu, and proc is a call back procedure 
that will be called when the user invokes the command from 
the Attention Menu. 

A call back procedure is a procedure that is passed in as a 
parameter to another procedure, and is later called by that 
procedure. Thus, you write a MenuProc but don't call it; you jst 
pass it to Createltem, and the MenuData implementation will 
call it when the user invokes your command. 
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The proc parameter is of type MenuData.MenuProc: 

MenuData.MenuProc: type = PROCEDURE [ 
window: window.Handle, 
menu: MenuOata.MenuHandle, 
itemData: longunspecified]; 

The parameters to this procedure are a handle to your 
application's window, a handle to the menu, and the itemData 
parameter that you passed to Createltem. window identifies a 
particular window on the screen, and menu identifies the 
menu from which the command was invoked. 

There is a MenuProc associated with every command in a 
menu, whether the command is in the menu of commands for 
an application, or in the Attention Menu. For some MenuProcs, 
you will need to use the window, menu, and itemData 
parameters. The examples in this chapter, however, do not use 
any of these parameters. (Section 4.4 discusses MenuProcs 
associated with commands in the header of an application.) 

itemData is referred to as client data; it is entirely for your own 
use. If there is no extra information that you need to have 
available in proc, you can leave itemData defaulted in the call 
to Createltem. 

Here is an example of how to add a command to the Attention 
Menu: 

—This procedure gets called from the mainline code 
Init: PROC ■ { 
command: xstring.ReaderBody <-Defs.Get[ 
Defs.Key.commandName]; 

Attention.AddMenuitem [ 
MenuData.Createltem [ 
zone : Heap.systemZone, 
name: ©command, 
proc: SampleMenuProc]] }; 

This procedure will add the command Sample Tool to the 
Attention Menu. When the user selects this command, 
Viewpoint will call the procedure SampleMenuProc. 
SampleMenuProc is then responsible for putting the 
application's window on the screen, as described in the next 
section. 



4.2 Creating a StarWindowShell 



When the user invokes your command from the Attention 
Menu, Viewpoint will call your MenuProc. Typically, the first 
thing you want to do is create a window on the screen. 

Viewpoint implements windows with something called a 
StarWindowShell. A StarWindowShell is a basic window that 
can have a title, commands, pop-up menus, and scrollbars 
(horizontal or vertical), as illustrated in Figure 4. 1 
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Figure 4.1 A StarWindowShell 



To create a shell, call starWindowShell.Create: 

StarWindowShell.Create: PROCEDURE [ 

transitionProc: starWindowSheiLTransitionProc <-nil , 
name:xstrinq.Reader nil , -The name of the tool 
namePicture:xstring.Character ^xchar.null, 
host: StarWindowShell. Handle NIL, 
type: starWindowSheli.ShellType <- regular, 
sleeps: boolean ^ false, --see below 
considerShowingCoverSheet: boolean <-true, 
currentlyShowingCoverSheet: boolean <- false, 
pushersAreReadonly: boolean <- false, 
readonly: boolean <- false, 

scrollData: starWindowSheii.ScrollData <- vanillaScrollData, 
garbageCollectBodiesProc: procedure [Handle] <-nil, 
isCloseLeqalProc: IsCloseLeqalProc <-nil . -See below 
bodyGravity: window.Gravity <— nw, 
zone: UNCOUNTED ZONE*- nil] 
RETURNS [StarWindowShell.Handle]; 

starWindowSheii.Handle: TYPE s RECORD [window.Handle]; 

Note that all of these parameters are defaulted, which means 
that they are all optional. However, most calls to Create include 
at least the first two (name and transitionProc.) We discuss 
transitioriProc and IsCloseLegaiProc below; for information on 
the other parameters, consult the StarWindowShell chapter of 
the Viewpoint Programmer's Manual. 
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Create returns a starWindowSheii.Handle, which is essentially a 
window.Handle. As mentioned earlier, a handle identifies your 
particular window; you will need to pass this handle to various 
procedures. 

Thus, the first part of your MenuProc will look like this: 

SampleMenuProc: MenuOata. MenuProc = { 
toolName: xstrmg.ReaderBody <-Defs.Get[ 
Defs.Key.toolName]; 

shell: StarWindowSheii.Handle <-StarWlndowShell.Create[ 

name: ©toolName]; 
...}; 



4.2.1 Transition procedures 



A transltionProc for a shell is a procedure that Viewpoint will 
call when the state of the shell is about to change: 

starWindowSheil.TransitionProc: type = procedure [ 
SWS: StarWindowSheii.Handle, 
state: StarWindowShell.State]; 

StarWindowShell.State: TYPE a 

{awake(O), sleeping, dead, last(7)}; 

A StarWindowShell is always in one of three states: awake, 
sleeping, or dead, awake indicates that the shell is currently 
displayed, sleeping indicates that the shell still exists, but is not 
being displayed and therefore you should free resources 
associated with the display state, dead indicates that the shell is 
about to be destroyed and therefore you should free all 
resources associated with the shell. If you have any storage 
associated with your shell, you should use a transitionProc to 
allocate and free that storage. Here is a "generic" example of a 
transition procedure: 

SimpleTransitionProc: StarWindowSheil.TransitionProc = 

BEGIN 

SELECT state FROM 

awake ■ > if data a nil then AllocateData[sws]; 
sleeping, dead s > FreeData; 
endcase; 
end; 



4.2.2 IsCloseLegalProc 



An IsCloseLegalProc allows you to veto an attempt to close 
your window. An IsCloseLegalProc is of type IsCloseLegalProc: 

starwindowSheii.lsCloseLegalProc: type = procedure [ 

SWS: StarWindowSheii.Handle, 

closeAII: boolean] returns [boolean]; 

closeAll indicates whether the current command is a Close or a 
CloseAII. 
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Viewpoint will call the isCloseLegalProc that you supply when 
either a user or a client program attempts to close the 
StarWindowShell. If it's okay to close the window, you should 
return true; otherwise, return false. (The isCloseLegalProc is 
also a convenient way to get control when the window is being 
closed.) Here is a simple example that prints a message and 
ignores the close under certain circumstances: 

SimplelsCloseLegalProc: starwindowSheii. IsCloseLegalProc s 

BEGIN 

\f-YouDon'tCarelfTheWinclowlsClosed- then return [true]; 
ELSE { "print a message, and then abort the close request 
abortMsg: xstring.Reader <-Defs.Get[Defs.Key.abortMsg]; 
Attention.Post[@abortMsg]; 

RETURN [false]}; 

end; 



4.3 Body windows 



Viewpoint windows are organized in a tree structure, with the 
desktop window at the root of the tree. The StarWindowShell 
for an application is generally a child of the desktop window. A 
StarWindowShell is just a shell, however; before the window 
can do anything useful, you need to put body windows \N'\th\n 
the StarWi ndowShel I . 

Body windows are what define the functionality of a shell. For 
example, if you want to display in a window, you display that 
information to a body window, not to the StarWindowShell. 
You can create various different arrangements of body 
windows, depending on what you want your application to do. 

The simplest arrangement is to have one very long body 
window that is much longer than the shell. This makes scrolling 
easy: you simply slide the body window within the window 
shell. This is how the StarWindowShell default scrolling works, 
so if you use this approach the StarWindowShell 
implementation will take care of all scrolling for you. 

However, if you use this approach, the dimensions of the body 
window won't change when the user changes the size of the 
shell. Thus, the body window may be much bigger or much 
smaller than the shell. 

An alternate way of handling body windows is to specify that 
the body window should change size whenever the size of the 
StarWindowShell changes. If you do this, you are responsible 
for keeping track of what is in the window, and you must 
perform all scrolling operations yourself. 

This chapter discusses only how to create a single body window 
whose size never changes. If you are interested in creating 
body windows that change size when the shell does, or if you 
want to create multiple body windows within a given shell, see 
the StarWindowShell chapter of the Viewpoint Programmer's 
Manual. 

To create a body window, you call starWindowSheii.CreateBody: 

StarWindowShell.CreateBody: PROCEDURE [ 

sws: StarWindowShell.Handle, -the StarWindowShell 
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repaintProc: procedure [window.Handle] <-nil, 
bodyNotifyProc: TiP.NotifyProc «- nil, 
box: Window.Box <- [[0,0] ,[0,29999]] ] 
RETURNS [window.Handle]; 

Window.Box: TYPE = RECORD [place: Place, dims: Dims]; 
window.Place: TYPE = userTerminai.Coordinate; -/x,y; /wrfGE/?/ 
Window. Dims: TYPE H RECORD [w,h: integer]; 

CreateBody creates a body window within the sws. The 
Window implementation will call repaintProc whenever it 
needs to redisplay part or all of the information in the body 
window. Chapter 6, Displaying information on the screen, 
discusses repaint procedures in detail. 

bodyNotifyProc is a procedure that is responsible for 
determining how the window handles user input; Chapter 8, 
TIP, discusses this subject in detail. 

box indicates the size and location of the body window within 
the shell. If box.dims.w and/or box.dims.h is zero, the body 
window will take on the dims.w and/or dims.h of the shell. If 
you are going to create one long body window, you should use 
box to specify the dimensions that you want the body window 
to have. For example, here is a code fragment from a 
MenuProc: 



-dimensions of the body window in pixels 
bodyWindowDims: window. Dims » [1000,1000]; 

- Create the StarWindowShell. 

shell: StarWindowShell.Handie a StarWindowShell.Create [ 
name: @sampleTool]; 

~ Create one long body window inside the StarWindowShell 
body: Window.Handle = StarWindowShell.CreateBodv [ 
sws: shell, 

box: [ [0,0], bodyWindowDims ], 

repaintProc: SomeRedisplayProc, -discussed in chapter 6 
bodyNotifyProc: SomeNotifyProc]; -d/sct/ssec//n chapters 



4.4 Commands 



StarWindowShells have commands in the header that the user 
can invoke. The commands can appear either directly in the 
header, or in a pop-up menu available from the header, as 
illustrated in Figure 4.2. 
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Figure 4.2 Commands 



Commands for an application work just like commands in the 
Attention Menu: when you specify a command, you associate a 
procedure (of type MenuData.MenuProc) with the command. 
When the user invokes the command, the corresponding 
procedure is called. 

StarWindowShell automatically puts the Close command in 
the header of every application, and you can also add 
additional commands. The following sections provide 
examples of how to put commands directly in the header and 
how to put them in a pop-up menu. (Note: if you specify 
commands in the header and they don't fit, they will 
automatically overflow into the popup menu.) 



4.4.1 Putting commands directly in the header 



To put commands in the header, you start by calling 
MenuData.Createltem to create an individual ItemHandle for 
each command. (Remember, this is what we did in the first 
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section, when we created the ItemHandle for the command in 
the Attention Menu.). Once you have called Createltem for 
each command that you want to have, you store them in an 
array, and then call MenuData.CreateMenu: 

MenuData.CreateMenu: procedure [ 
zone: uncounted zone, 
title: MenuData.ltemHandle, 
array: MenuData-ArrayHandie, 
copyltemslntoMenusZone: boolean false] 
RETURNS [MenuData.MenuHandle]; 

MenuData.ArrayHandle: TYPE ■ long descriptor for array of 
MenuData.ltemHandle; 

This procedure returns a handle to a menu; you can then put 
the "menu" of commands in the header. (Note: the idea that 
commands in the header are actually a menu may seem a bit 
strange, but in fact a command in the header is considered to 
be an individual menu item with a box around it.) 

Finally, you call starWindowShell.SetRegularCommands to display 
the commands in the header: 

starwindowSheii.SetRegularCommands: procedure [ 
SWS: StarWindowShell.Handle, 
commands: MenuData.MenuHandle] ; 

Here is an example of how to create the commands Add, 
Multiply, and Subtract, and put them directly in the header: 

~ retrieve zone attached to the StarWindowShell 

z: UNCOUNTED ZONE <-StarWindowSheil.GetZone [shell]; 

-declare ReaderBodys for the commands that you want to have 

add: xstring.ReaderBody <-xstring.FromSTRING ["Add"]; 

subtract: xstring.ReaderBody <- xstring.FromSTRING["Subtract"L]; 

multiply: xstring.ReaderBody <- xstring.FromSTRING["l\/Iultipiy"L]; 

-call Createltem for each command, passing in the ReaderBodys 

-and a call back procedure for each command. Store the 

- ItemHandles into an array. 

items: array [0..3) of MenuData.ltemHandle <- [ 

MenuData.Createltem[zone: z, name: @add, proc: Add], 
MenuData.Createltem [zone: z, name: ©subtract, 

proc: Subtract], 
MenuData.Createltem [zone: z, name: ©multiply, 
proc: Multiply]]; 

-Create a MenuHandle by calling CreateMenu, passing in 

—a descriptor for the array of ItemHandles. 

myMenu: MenuData.MenuHandle s MenuData.CreateMenu [ 

zone: z, - Generally use zone attached to SWS 

title: NIL, 

array: descriptor [items]]; 

-specify that the commands should appear as individual 
-items in the header. 
starwindowSheii.SetRegularCommands[ 
sws: shell, commands: myMenu]; 

The first step is to retrieve the heap attached to the shell . When 
you call starWindowShell.Create to create a StarWindowShell, the 
implementation creates a private heap and uses it as storage 
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for all shell-related items, such as name strings. It is a good idea 
to use this zone for your own storage, since it will be deleted 
when you delete the StarWindowShell. 

The next step is to call MenuOata.Createltem once for each 
command, and store the individual ItemHandles into an array. 

Once you have an array of ItemHandles, you can call 
CreateMenu, which puts the array into a menu and returns a 
MenuHandle. The last step is to pass that MenuHandle to the 
proced u re starwindowSheii.SetRegu larCom ma nds. 



4.4.2 Putting commands in a popup menu 



Putting the commands in a pop-up menu is much like putting 
them directly in the header, except that you need to include a 
title for the menu, and you need to call AddPopupMenu 
instead of SetRegular Commands: 

starwindowSheii.AddPopupMenu: procedure [ 

sws: StarWindowShell. Handle, menu: MenuData. MenuHandle] ; 

Here is an example of how to put commands in a pop-up menu: 

- retrieve zone attached to the StarWindowShell 

z: uncounted ZONE <-starWindowSheii.GetZone [shell]; 
--declare ReaderBodys for the commands and the title 
add: XString.ReaderBody <-XString.FromSTRING ["Add"]; 
subtract: xstrlng.ReaderBody <- xstring.FromSTRING["Subtract"L]; 
multiply: xstring.ReaderBody <- xstring.FromSTRING["Multiply"L]; 
title: xstrlng.ReaderBody ^-xstring.FromSTRING ["Function"]; 

-call Createltem for each command, passing in the ReaderBodys 

- and a call back procedure for each command. Store the 
ItemHandles into an array. 

items: array [0..3) of MenuData.ltemHandle <- [ 
MenuData.Createltem[zone: z, name: @add, 
proc: Add], 

MenuOata.Createltem [zone: z, name: ©subtract, 

proc: Subtract], 
MenuOata.Createltem [zone: z, name: ©multiply, 

proc: Multiply]]; 

-Create a menu item for the title (but don't store it in array.) 

- Notice that there is no proc; when the user invokes this 
-command, MenuData will display the menu. 
titleltem: MenuData.ltemHandle <- MenuOata.Createltem [ 

zone: z, name: ©title, proc: nil]; 

-Create a MenuHandle by calling CreateMenu, passing in 
-a descriptor for the array of ItemHandles. 
-Notice that title is not NIL. 

myMenu: MenuData. MenuHandle s MenuData. CreateMenu [ 
zone: z, -- Generally use zone attached to SWS 
title: titleltem, 
array: descriptor [items]]; 

-specify that commands should appear in menu. 
StarWindowShell.AddPopupMenu[ 
sws: shell, commands: myMenu]; 
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4.5 Displaying windows on the screen 



Once you have created a window shell, body window, and 
associated commands, you still need to display the shell on the 
screen. (Note that Create generates a StarWindowShell but 
does not display it on the screen.) To display a shell on the 
screen, call starWindowShell.Push, which inserts the new window 
into the existing tree structure: 

StarWindowShell.Push: PROCEDURE [ 

newSheil: starwindowsheii. Handle, 
topOfStack: starwindowSheii.Handle <-nil, 
poppedProc: starwindowSheii.PoppedProc <- nil]; 

Push displays newShell by inserting it into the visible window 
tree. If poppedProc is nil, popping newShell will destroy the 
shell. You can write your own PoppedProc if you want to do 
something other than destroy the shell; see the ViewPoint 
Programmer's Manual for details. 

You can remove a StarWindowShell from the screen by calling 
StarWindowShell. Pop. You will almost never call this procedure 
yourself, however; it is usually called by StarWindowShell as 
the result of an operation such as Close!. 



4.6 Summary 



To create a bare-bones user interface for a new application, 
you need to do the following: 

1. In your initialization code, add a command to the Attention 
Menu with the following steps: 

A. Call MenuData.Createltem to create an ItemHandle. The 
most important parameters to this procedure are the 
name of the command and the call back procedure that 
Viewpoint will call when the command is invoked. 

B. Call Attention.AddMenultem to add your new command 
to the Attention Menu. 

2. In your MenuProc, do the following: 

A. Call starWindowShell.Create, which creates a window shell. 
You can optionally associate a TransitionProc and an 
IsCloseLegal procedure with your shell. 

B. Call starWindowSheil.CreateBody to create one or more 
body windows within the StarWindowShell. There are 
many different possible arrangements of body windows; 
this chapter discussed only the simplest case. 

C. Add commands to the shell with the following steps: 

1. Call MenuData.Createltem to get an Itemhandle for 
each command. Store the ItemHandles into an array. 

2. Call MenuData.CreateMenu to create a menu of 
commands. If you want the commands to appear in a 
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popup menu, you need to include a title in the call to 
CreateMenu; if you want the commands to appear 
directly in the header, you don't need a title. 

3. Call either starWindowSheti.SetReguiarCommands or 
starwindowSheii.AddPopupMenu, depending on 
whether you want your commands to appear 
directly in the header or in a popup menu. 

D. Display the window on the screen with a call to 
StarWIndowShell.Push. 

Here is a complete example: 

< < This is a sample tool that you can use as a template for 
creating a new user interface. We will add to this program in 
the next few chapters. 

This tool adds the command Sample Tool to the attention 
window menu. When the user invokes this command, the 
MenuProc creates a StarWindowShell with a single body 
window in it The commands Post and Redisplay are placed in 
the header of the StarWindowShell. > > 

DIRECTORY 

Attention using [AddMenultem, Post], 
Heap USING [systemZone], 

MenuData using [Createltem, CreateMenu, ItemHandle, 

MenuHandle, MenuProc], 
StarWindowShell using [Create, CreateBody, GetZone, 

Handle, Push, SetRegularCommands], 
Window using [Dims, Handle], 

XString using [FromSTRING, ReaderBody, WriterBody]; 

SampieTool: program 

IMPORTS Attention, MenuData, StarWindowShell, XString = 
begin 

- Constant; used for size of body window 
bodyWindowDims: window.Dims = [1000,1000]; 

--Procedures 

< < This procedure is called from the mainline code. It registers 
the command Sample Tool in the Attention Menu. When the 
user invokes this command, MenuProc will be called. > > 

I nit: PROC s { 
command: xstring.ReaderBody ^ 

Defs.Get[Defs.Key.commandNmae]; 
Attention.AddMenultem [ 
MenuData.Createltem [ 
zone: Heap.systemZone, 
name: @commandName, 
proc: MenuProc] ]; 

}; 
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< < Called when the user invokes the Sample Tool command. 
Create a StarWindowShell, a single body window within that 
shell, and some commands, and then display the shell on the 
screen. >> 

MenuProc: MenuData.MenuProc s { 
redisplay: xstring.ReaderBody <- 

xstring.FromSTRING["Redisplay"L]; 
post: xstring.ReaderBody f-xstring.FromSTRING["Post"L]; 
sampleTool: xstring.ReaderBody 

xstring.FromSTRING["SampleToor'L]; 

~ Create the StarWindowShell. 

shell: StarWindowShell. Handle B StarWindowShell.Create [ 
name: @sampleTool]; 

~ Create one long body window inside the shell. 
body: window.Handle a starWindowSheii.CreateBody [ 
sws: shell, 

box: [ [0,0], bodyWindowOims ], 

repaintProc: SomeRedlsplayProc, -chapters. Display 

bodyNotifyProc: SomeNotifyProc];-c/7apter5, TIP 

-Get the zone attached to the window shell and use it 
-to create the menu items. 

z: UNCOUNTED ZONE <-starWindowSheii.GetZone [shell]; 

-Create an array of menu items 

items: array [0..2) of MenuOata.itemHandle <— [ 

MenuData.Createltem [zone: z, name: ©redisplay, 
proc: RedisplayMenuProc], 

MenuData.Createltem [zone: z, name: @post, proc: Post]]; 

-Create the menu. If you want to put commands directly in 
-the header, title can be NIL; if you want to put them in 

- a popup menu, you need to include a title. 

myMenu: MenuData.MenuHandle s MenuData.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items]]; 

- Add the menu to the StarWindowShell header. 
starWindowSliell.SetRegularCommands [sws: shell, 

commands: myMenu]; 

~ Put the StarWindowShell on the screen. 
StarWindowShell.Push [shell]; 

}; 

-Procedures to implement the commands in the header. 
Post: MenuData.MenuProc a { 

msg: xstring.ReaderBody 

oefs.Get[Defs.Key.sampleMessage]; 

Attention.Post [@msg]}; 

RedisplayMenuProc: MenuData.MenuProc s { 
-chapter 6 discusses how to display on the screen}; 

- Mainline code 
lnit[]; 

END... 
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4.4 Exercise 



The exercise for this chapter is to write the user interface for a 
simple tool, called DMT. This tool takes a string and displays it 
in random places in the tool's window, much like the DMT 
program that runs in XDE. This tool registers the command 
DMT Tool in the Attention Menu. Figure 4.3 illustrates the 
window that will appear when the user invokes this command. 




Figure 4.3 The DMT Tool 



Invoking the Start command will take the current selection, if it 
is a string, and display it in the window at random locations. If 
the current selection cannot be recognized as a string, the 
default string will be My DMT. (Note that the selected string 
must be in a simple document, not a standard document.) 

Invoking Stop will stop the DMT. You can only have one DMT 
at a given time. Invoking Close will destroy the window. 

Your job is to write the following procedures: 

Init This procedure registers the DMT Tool 

command in the AttentionMenu. 

MenuProc This procedure is called when the user 

invokes DMT Tool command. This procedure 
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should create the shell and display it on the 
screen. 

IsCloseLegalProc This is the IsCloseLegalProc parameter to 
StarWindowShell.Create. 

Redisplay This is the repaintProc parameter to 

starWindowSheii.CreateBody. 

Start This is the command procedure for the Start 

command. 

Stop This is the command procedure for the Stop 

command. 

We provide a template, called DMTExercise.mesa, that contains 
detailed instructions for each of these procedures. To run the 
program, you will also need the files DMTDefs.bcd, 
DMTImpl. bed, and DMTConfig. mesa. 
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In general, you should structure applications so that the user 
can run more than one copy ("instance") simultaneously.This 
doesn't typically involve much restructuring, but it does create 
a problem with storage for global data. 

All copies of an application share the same global frame, so 
you can't use the global frame to store data that will be 
different for each instance of the application. Examples of such 
window-relative data include the contents of the window, a 
handle to the StarWindowShell itself, the state of some options 
associated with the window, and so on. 

Viewpoint solves this problem with the notion of a context. A 
context is a data object associated with a window instance; 
contexts allow you to store global state information with a 
window rather than in the program's global frame. This 
approach has the additional advantage that it helps minimize 
global frame size, which is an important consideration. 



5.1 Context types 



To use contexts, the first step is to get a context type for your 
application. Every client of the Context interface has a unique 
type; this is how the client identifies itself in later calls to the 
Context interface. Figure 5.1 illustrates this idea; notice that 
each window has the same context type but distinct data. 



Application 
(data in global frame) 




Context type a 


33777B 


X = 5, 




y = lO, 




zbO 






Context type = 


33777B 


x = 22. 




y = 6. 




z = 45 






Context type ■ 


33777B 


Xa12, 




y = 9. 




Za3 





Figure 5.1 : Contexts 
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To get a context, call contextUniqueType: 

-Note that all instances share one context type 
context: Context.Type <-Context.UniqueType[]; 

This call returns a context type. You don't need to know 
anything about the actual number that the type represents; 
you just need to use it in future calls to the Context interface. 

You only need to make this call once for each time the 
application is run, not once for each instance of the window, 
since every instance of a given application uses the same 
context type. Thus, you should store your context type in the 
shared global frame. 



5.2 Creating the context 



The next step is to allocate the data that you want to keep in 
your context. You need to allocate a context each time that 
you initialize an instance of the window with which you are 
going to associate the context; this will typically be in your 
MenuProc. You can associate the context either with the shell 
or with a particular body window. 

To allocate a context, call contextCreate: 

context.Create: procedure = [ 
type: Context.Type, 
data: Context. Data, 
proc: Context.DestroyProcType, 
window: window.Handle]; 

Context. Data: TYPE = long pointer to unspecified; 

Context.DestroyProcType: TYPE = procedure [ 
data: Context.Data, 
window: window.Handle]; 

type is your unique context type, data is the data that you want 
to keep in the context, proc is a procedure that the system will 
call to free the context when it is about to destroy the window, 
and window is the body window with which you want to 
associate the context. 

Notice that Data is a pointer to an unspecified data structure; 
this means that it can be a pointer to any data structure you 
declare. Obviously, there is no general structure for this data; 
every application will be different. You should declare a type 
that represents the data you want to keep in your context. For 
example, the data for a game might look like this: 

-global type declaration 

DataObject: type ■ record [ 

currentUser: xstring.ReaderBody <-xstring.nullReaderBody, 
level: {beginner, intermediate, advanced} <— beginner, 
score: cardinal <- 0]; 

The actual call to Create would then look like this: 
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Context.Create [ 

type: context, -your context type 

data: sysZ.NEW[DataObject]; -data to be stored in context 

proc: DestroyContext, 

window: body]; -body window for context 

The call to Create allocates a DataObject, associates it with 
type, and stores it with window. 

DestroyContext is a procedure that is responsible for 
deallocating the storage associated with the context. When it is 
about to destroy a window with an associated context 
(typically in response to a Close command), Viewpoint will call 
Context.Destroy, which will in turn call your DestroyProc. (If you 
like, you can call Destroy yourself, but this is rare. You never 
call your DestroyContext procedure directly.) 

Your DestroyContext procedure should deallocate the context 
data. The Context interface provides two procedures of this 
type: 

Context. NopDestroy Proc: context. Destroy ProcType; 
Context.SimpleDestroyProc: Context. Destroy ProcType; 

NopDestroyProc does nothing; SimpleDestroyProc just 
deallocates data from the system heap. Thus, if you allocate 
your context from the systemZone, you can use 
SimpleDestroyProc instead of writing your own DestroyProc. If 
you use a private heap to allocate your data, or if you have 
additional deallocation that you need to do, then you should 
write your own DestroyProc. Here is a simple example of a 
DestroyProc: 

DestroyContext: Context. Destroy ProcType = { 
z.FREE[@data]}; 



5.3 Using the context 



Once you have stored the context, you can retrieve it at any 
point to inspect or change the information in the context. To 
retrieve your context, call Context.Find or Context.Acquire: 

Context-Find: procedure [type: Context.Type, 

window: window.Handle] returns [context. Data]; 

Context-Acquire: procedure [type: Context.Type, 
window: window.Handle] returns [context.Data]; 

These procedures both retrieve the data associated with a 
particular context (type specifies which context to retrieve). The 
difference between the two is that Acquire monitors the data 
so that only one process can have the context at a time. You 
can use either one, depending on the needs of your 
application. 

The only case where retrieving the context is slightly tricky is 
when you have the wrong window handle: that is, if the 
context is associated with the body window, and you have a 
handle to the shell, or vice versa. 
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If you have a body window, and would like the shell, you can 
call starwindowSheii.ShellFromChild; if you have the shell and 
want the body window, you can call starwindowSheii.GetBody to 
get a handle to the body window. (Note that this only works if 
there is only one body window.) 

StarwindowSheii.GetBody: PROCEDURE [ 

Sws: StarWindowShell.Handle] RETURNS [window.Handle]; 

starWindowSheii.ShellFromChlld: procedure [ 

child: Window.Handle] returns [starWindowSheii.Handle]; 

Here is an example of retrieving the context: 

-This procedure actually retrieves the context It is called 
--from various other procedures 

GetContext: proc [body: window.Handle] returns [data: Data] 
a {data ^Context. Find [context, body]; 
return [data]}; 

-This procedure makes the game more difficult, if possible. 
-If the player is already an expert,call another procedure to 
-post an appropriate message. 
MakeGameHarder: MenuData.MenuProc s { 

body: window.Handle ■ -get handle to body window 

StarwindowSheii.GetBody [[wi ndow]] ; 
data: Data ^GetContext[body]; -Find context 
SELECT data. level from 

beginner ■ > data. level <- intermediate, 
intermediate = > data. level «- expert, 
expert = > MessageUser[expert]; 
endcase}; 

}; 

In this case, we have associated the context with the body 
window, and not the shell. Thus, inside the MenuProc we need 
to call GetBody, since we have a handle to the 
StarWindowShell (which was passed in to the MenuProc), but 
we don't have a handle to the body window itself. 



5.4 Summary 



To allow the user to have multiple copies of your application, 
you need to do the following: 

1. Declare a Context.Type in your (shared) global frame, and 
initialize it with a call to Context. Uniquely pe. 

2. Create the context with a call to Context.Create. You should 
make this call in your window creation code, after you 
create the body window with which you are going to 
associate the context. One of the parameters to Create is a 
call back procedure to destroy the context. 

3. Access the context as often as necessary with context.Find or 
Context.Acquire. 

4. Include a command (such as Another) so that the user can 
conveniently create new instances of the application. (The 
Close command will destroy an instance.) 
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To illustrate the use of contexts, here is the example from the 
last chapter, with the addition of Context information. 

DIRECTORY 

Attention using [Add Menu Item, Post], 

Context USING [Create, Data, Find, Type, UniqueType], 

Heap USING [systemZone], 

MenuData using [Createltem, CreateMenu, ItemHandle, 

MenuHandle, MenuProc], 
StarWindowShell using [Create, CreateBody, GetZone, 

Handle, Push, SetRegularCommands], 
Window USING [Dims, Handle], 

XString using [FromSTRING, nuilReaderBody, ReaderBody, 
WriterBody]; 

SampleVPTool: program 

IMPORTS Attention, Context, MenuData, StarWindowShell, 
XString = begin 

- TYPES 

Data: TYPE a long pointer to DataObject; 
DataObject: type ■ record [ 

currentUser: xstring.ReaderBody <- xstring.null ReaderBody, 

level: Level <- beginner, 

score : long cardinal ^ 0 ] ; 

Level: type a {beginner, intermediate, advanced} 

- Constants 

bodyWindowDims: window.Dims = [1000,1000]; 
sysZ: uncounted ZONE = Heap.systemZone; 

~ Shared global data 

context: Context.Type <- Context. UniqueType[] ; 
--Procec/ures 

-This procedure retrieves the context associated with a given 

- body window and returns it to the calling procedure. 
GetContext: proc [body: window.Handle] returns [data: Data] 
a {data <-Context.Find[context, body]; 

IF data a nil then error; -7ust mease. 
RETURN [data]; }; 

-Register the command Sample Tool in the Attention Menu. 
Init: PROC = { 
sampleTool: xstring.ReaderBody <r- 

xstring.FromSTRING["SampleTool"L]; 
Attention.AddMenultem [ 
MenuData. Createltem [ 

zone: Heap.systemZone, 
name: ©sampleTool, 
proc: MenuProc] ] }; 
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< < This procedure is called when the user ir)vokes the Sample 
Tool command from the Attention Menu or the Another 
command from the header. It creates a StarWindowShell, 
creates a single body window within that shell, allocates a 
context to go with that body window, adds some commands to 
the shell, and then displays the shell on the screen. > > 
MenuProc: MenuData.MenuProc = { 
another: xstring.ReaderBody <— 

xstring. FromSTRING[" Another" L]; 
redisplay: xstring.ReaderBody <— 

xstring. FromSTRING["' Redisplay" L]; 
post: xstring.ReaderBody <— xstring. FromSTRING["Post"L]; 
sampleTool: xstring.ReaderBody <— 

xstring. FromSTRING["Sample Tool " L]; 
~ Create the StarWindowShell. 
shell: StarWindowShell. Handle = StarWindowShell. Create [ 
name: ©sampleTool]; 

- Create a body window inside the StarWindowShell. 
body: window.Handle = starWindowSheii.CreateBody [ 

sws: shell, 

box: [ [0,0], bodyWindowDims ], 

repaintProc: SomeRedisplayProc, -chapter 6, Display 

bodyNotifyProc: SomeNotifyProc ];-Chapter8, TIP 

-Get the zone attached to the window shell and use it 
-to create the menu items. 

z: UNCOUNTED ZONE <— StarWindowShell. GetZone [shell]; 
items: array [0..3) OFMenuData.itemHandle <— [ 
MenuData.Createltem [zone: z, name: ©another, 

proc: MenuProc], 
MenuData.Createltem [zone: z, name: ©destroy, 

proc: DestroyMenuProc], 
MenuData.Createltem [zone: z, name: ©post, proc: Post] 
]; 

-Create the menu. 

myMenu: MenuData.MenuHandle = MenuData.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items]]; 

- Add the menu to the StarWindowShell header. 
StarWindowShell. SetRegularCommands [sws: shell, 

commands: myMenu]; 

~ Create a context and "hang it" from the body window. 
context.Create [ 
type: context, 

data: sysZ.NEW[DataOb]ect], 
proc: Context.SimpleDestroyProc, 
window: body]; 

~ Put the StarWindowShell on the screen. 
StarWindowShell. Push [shell]; 

}; 
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< < Procedures to implemerit header commands. Note that the 
Ar\other command just calls MenuProc again. Recall that 
window is a parameter to the MenuProc. > > 
Post: MenuData. MenuProc a { 
msg: xstring.ReaderBody; 

body: window.Handle » starWindowShell.GetBody[[window]]; 
data: Data GetContext [body]; 
IF xstring.Empty[data.currentUser] then 

msg^ xstring.FromSTRING ["No current user."L] 
ELSE msg ««-...; 
Attention. Post [@msg]; 

}; 

see chapter 6, Displaying information on the screen 
RedisplayMenuProc: MenuData.MenuProc ■ { }; 

~ Mainline code 
InitH; 

END... 



5.5 Exercise 



The exercise for this chapter is to take your solution to the 
exercise for the last chapter and modify it so that you store the 
global tool data in a context rather than in the global frame. (If 
you did not do the exercise for the last chapter, you should 
retrieve our solution from the file server and modify it for this 
exercise.) 

Once again, there is a template, in this case called 
DMTExercise2.mesa, that describes exactly what you need to 
write. You will also need the following files: 

DMTDefs.mesa 
DMTImpl.mesa 
DMTConfig2.mesa 

The interface and the implementation file are identical to the 
ones in the last chapter; the configuration file is slightly 
different.. 
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Notes: 
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6. ON THE SCREEN 



Most applications need to display some sort of information on 
the screen. For example, the document editor needs facilities to 
display text and user-defined graphics, and the loader needs to 
display a list of applications. This chapter describes how to use 
the Window, Display and SimpleTextDisplay interfaces to 
display text and graphics in a body window. 



6.1 Overview 



In general, every application that displays information on the 
screen has a display procedure that actually paints the display. 
When called, this procedure can display all or part of the 
information in the application's window. The display 
procedure typically creates the display based on an associated 
data structure that represents the current data. 

A display procedure is a call back procedure: the system calls 
the appropriate display procedure when it needs to repaint a 
particular portion of the screen. The system decides when to 
paint a window by keeping an invalid list This list represents 
portions of the screen that contain invalid information. For 
example, if the user uncovers a window that was previously 
covered by another window, the window implementation will 
call the display procedure for the window that is being 
uncovered. A client can also call the window implementation 
to specify that a portion of its display has become invalid. 

The window implementation accumulates invalid areas until a 
client requests a screen validation. At that point, it will call the 
appropriate display procedures to repaint the screen. 

When performance is critical, an application can also paint 
directly to the screen instead of going through the display 
procedure. Even if you choose to display directly to the screen, 
however, you still need to provide a display procedure. 
(Otherwise, when the user moves another window on top of 
yours and then moves it back, there will be no way for the 
window implementation to repaint the display.) This chapter 
has examples of both methods. 



6.2 Invalidating and validating 



Either a client or a user can invalidate a portion of the screen. 
The window package handles repainting as the result of user 
actions, but if your program changes something that 
invalidates your application's display, you are responsible for 
ensuring that the display is correctly updated. 
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To Specify that a portion of the screen contains invalid 
information, you call InvalidateBox: 

window.lnvalidateBox: procedure [ 
window: window.Handie, 
box: Window. Box, 
clarity: window.Clarity <- isDirty]; 

window.Box: TYPE ■ record [ 

place: window.Place, dims: window.Dims]; 

window.Place: type = UserTerminal.COOrdinate; 

Window.Dims: type = record [w, h: integer]; 

Window.Clarity: TYPE ■ {isClean, isDirty}; 

box describes an invalid region with its position in the window 
and its dimensions (width and height), place is relative to the 
window's upper-left corner, which is defined to be at [0,0]. The 
place, width, and height are all measured in pixels. 

clarity specifies the current state of the window. isClean means 
that the region is already white and there is nothing to erase; 
isDirty means that there is some information displayed that the 
system should erase before it displays the new information. 

Calling Invalidate does not actually initiate a repaint 
operation; it merely adds the specified area to the invalid list 
for that window. To initiate the repaint, you need to call either 
Validate or ValidateTree: 

window.Validate: procedure [window: window.Handie]; 

window. ValidateTree: procedure [ 

window: window.Handie <- window.rootWindow]; 

Calling Validate will affect only your window; calling 
ValidateTree will update the tree of windows whose root is 
window. As a simple example of calling Invalidate and 
Validate, suppose that your application has a Redisplay 
command in the header. When the user invokes this command 
you should invalidate the entire window and then validate it: 

RepaintMenuProc: MenuData.MenuProc s { 

body: window.Handie a starWindowShell.GetBody[[window]]; 
window.lnvalidateBox[body, [[0, 0], [30000, 30000] ]]; 
Window. Validate[body]; }; 

Recall that within a MenuProc you have a handle to the 
StarWindowShell and not the body window. Thus, as in the 
example above, you must get a handle to the body window 
before you do the invalidation and validation. 

The [30000, 30000] dimensions are arbitrary; they just need to 
be large enough to guarantee that you invalidate the entire 
window. It is never wrong to invalidate a box that is larger than 
you really need; the window implementation ensures that you 
cannot paint outside the boundary of your window. 
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6.3 Writing a display procedure 



The display procedure is of type window.DisplayProc: 

window.DlsplayProc: type a procedure [ 
window: window.Handle]; 

Within a display procedure, you have two choices for how to 
display information. You have access to a list of invalid regions 
for the window, and you can repaint just the invalid regions, or 
you can ignore the list and repaint the entire window. 

If you want to enumerate the invalid regions and repaint each 
one individually, you call window.EnumeratelnvaiidBoxes: 

window.EnumeratelnvalidBoxes: procedure [ 
window: window.Handle, 
proc: procedure [window.Handle, window.Box]]; 

EnumeratelnvalidBoxes will call proc once for each box on 
window's invalid list, passing in the window handle and the 
invalid region. The window passed to proc is the same as the 
window passed to EnumeratelnvalidBoxes; this should be the 
body window (the window parameter to the DisplayProc.)proc 
is responsible for redisplaying the correct information in the 
specified region. 

You must call EnumeratelnvalidBoxes from within a 
DisplayProc. Here is an example of using this method: 

DisplayGraphicSW: window.DisplayProc s 

BEGIN 

data: DataHandle s FindContext[window]; 

RepaintGraphicSW: proc[ 

window: window.Handle, box: window.Box] » 
{RepaintBox[data. bitmap, window,box]}; 

window.EnumeratelnvalidBoxes[ 
window, RepaintGraphicSW]; 
end; 

When this display procedure is called, it makes two calls: one to 
FindContext, and the other to EnumeratelnvalidBoxes. The call 
to EnumeratelnvalidBoxes will in turn result in a call to 
RepaintGraphicSW for each of the invalid boxes in window; 
RepaintGraphicSW is then responsible for repainting the area 
described by box. For now, don't worry about how RepaintBox 
displays to the screen; the following sections discuss this. 

The other way to write a DisplayProc is to ignore the invalid list 
and just repaint the entire window. This isn't as inefficient as it 
sounds, because ViewPoint keeps a bad phosphor list for each 
window. The bad phosphor list consists of the visible portions 
of the window's invalid areas; it thus represents the parts of 
the window that need to be repainted. If your DisplayProc 
ignores the invalid list and repaints the entire window, the 
painting will be clipped to this list. This means that the window 
implementation will only paint areas that are on the bad 
phosphor list, and will ignore requests to paint other areas. 
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Thus, even when you try to repaint the entire window, the 
window implementation will only repaint the areas that are 
both invalid and visible. Thus, you should usually just repaint 
your entire window within the DisplayProc; you only need to 
use the EnumeratelnvalidBoxes method when there is no bad 
phosphor list (the window has never been validated) or when 
redisplaying the entire window will take too long. 

Whichever method you use, your display procedure should not 
change the data structure; it should just paint the screen. To be 
safe, you should generally monitor your display data structure 
and make the display procedure an entry procedure. (See 
section 50.3.1 of the ViewPoint Programmer's Manual for a 
complete discussion of this problem.) 

The following sections discuss how to use the facilities of the 
SimpieTextDlspiay and Display interfaces to actually paint 
information on the screen. 



6.3.1 SimpleTextDisplay 



The SimpleTextDisplay interface provides facilities for 
displaying text in a window. The primary procedure in this 
interface is StringlntoWindow: 

SimpieTextDisplay.StrlnglntoWindow: procedure [ 
string: xstring.Reader, 
window: window.Handle, 
place: window.Place, 
I i neWidth : cardinal <- cardin allast, 
maxNumberOf Lines: cardinal <- 1, 
lineToDeltaY: cardinal *-o, 
wordBreak: boolean <- true, 
flags: BitBit.BitBltFlags <-Dispiay.paintFlags] 
returns [lines, lastLineWidth: cardinal]; 

This procedure displays string in window, starting at place. The 
other parameters describe formatting details; see the 
SimpleTextDisplay documentation for details. For example: 

Redisplay: Window. DisplayProc a { 
data: Data ^GetContext [window]; 
writerBody: xstring.WriterBody «-xstring.NewWriterBody [ 

maxLength: 250, z: sysZ]; 
xfo: XFormat.Object XFormat.WriterObject [ 

w: @writerBody]; 

-put text and value of data. count in string 
xFormat.String [h: @xfo, s: "This is a string displayed in a 

body window using StringlntoWindow. The current 

value of data.count is "L]; 
XFormat.Decimal [h: @xfo, n: data.count]; 

"display the string 

[] «- SimpleTextDlsplay.StringlntoWindow [ 

string: xstring.ReaderFromWriter [@writerbody], 
window: window, -The body window 
place: [10,10], -Upper- left corner is [0,0] 
I i ne Width : 300, -number of pixels wide 
maxNumberOfLines: 10]; -Arbitrary- }; 
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This display procedure displays a constant string and the 
current value of data.count. data.count is just a count of 
something interesting; it doesn't matter exactly what is being 
counted. (Remember, window is a parameter to the 
DisplayProc; it specifies the body window that is to be 
painted.) Notice that the information displayed in the window 
depends on the value of the variable count; if your program 
changes the value of count, you need to do an Invalidate and 
then a Validate to update the display. 



6.3.2 Display 



The Display interface provides procedures to paint points, 
lines, bitmaps, repeating patterns, boxes, circles, arcs, ellipses, 
and so on. Because of the wide variety, we won't try to cover all 
of the routines in this interface. As examples, however, here 
are the declarations of two of the more common Display 
procedures: 

Dispiay.Black: procedure [ 
window: window.Handle, 
box: Window.Box]; 

Dispiay.Bitmap: procedure [ 
window: window.Handle, 
box: Window.Box, 
address: Environment.BltAddress, 
bitmapBitWidth: cardinal, 
flags: Biteit.BltBltFlags <- paintFlags]; 

Environment.BltAddress: TYPE a MACHINE DEPENDENT RECORD [ 

word: long pointer, 

reserved: [O..LAST[wORD]/Environment.bitsPerWord) <-0, 
bit: [O..Environment.bitsPerWord)]; 

Black just paints the specified portion of the display black. 
There are similar procedures to paint a portion white or to 
invert it. 

Bitmap displays the bitmap specified by address and 
bitmapBitWidth into box in window. 

bitmapBitWidth specifies the width of the bitmap in pixels. 
This must be a multiple of 16. 

address is the field that describes the bitmap to be painted. 
Within an address, word is a pointer to an array of bits (the 
actual bitmap.) reserved and bit are primarily for the purposes 
of lower-level routines; for the purposes of this course, they 
will both always be 0. 

flags specifies how Bitmap should interact with the pixels that 
are already displayed in the specified area. The default, 
paintFlags, specifies that black source pixels should cause black 
display pixels, and white source pixels have no effect. There are 
various other alternative ways to interact with existing pixels, 
such as XORing; check the Display chapter of the ViewPoint 
Programmer's Manual for details. 
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6.3.2.1 Example: Checkerboard 



Here is a DisplayProc that draws the checkerboard in Figure 
6.1. 
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Figure 6. 1 : The checkers display 



DisplayProc: window.DlsplayProc a { 

boardWidth: integer <-(8*Defs.squareDims.w) + 8; 

checkerWidth: integer ■ oefs.squareDims.w; 

checkerHeight: integer = Defs.squareDims.h; 

-the offset is the difference between the upper left hand 

-corner of the window and the upper left hand corner of 

-the checkerboard 

off setWidth : integer <r- oef s.off set. w; 

offsetHeight: integer <-Def s.off set. h; 

mydata: Defs.Data GetContext[window]; 

-draw edges of checkerboard. Use boxes of width 1 pixel 
Display.Black[ -upper left to upper right 
window: window, 

box: [place: [offsetWidth, offsetHeight], 
dims: [boardWidth, 1]]]; 
Display.Black[ -lower left to lower right 
window: window, 
box: [place: [offsetWidth, 

(OffsetHeight + boardWidth)], 
dims: [boardWidth, 1]]]; 
Dispiay.Black[ -lower left to upper left 
window: window, 

box: [place: [offsetWidth, offsetHeight], 
dims: [1, boardWidth]]]; 
Display. Black[ -lower right to upper right 
window: window, • 

box: [place: [(offsetWidth + boardWidth), 
offsetHeight], 
dims: [1, boardWidth]]]; 
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~ Use Display. Line instead of Display. Black for variety 
"draw 7 horizontal lines to make 8 boxes. 

FOR i : CARDINAL IN [1 ..8) DO 
Display.Line[ 

window: window, 
start: [x: offsetWidth + 0, 

y: (offsetHeight + i*(checl<erHeight + 
stop: [x: (offsetWidth + boardWidth), 

y: (offsetHeight + i*(checkerHeight + 1))]]; 

-draw 7 vertical lines 
Dispidy.Line[ 

window: window, 

start: [x: (offsetWidth + i*(checl<erWidth + 1)), 

y: offsetHeight + 0], 
stop: [x: (offsetWidth + i*(checl<erWidth + 1)), 
y: (OffsetHeight + boardWidth)]]; 

ENDLOOP; 

-draw gray boxes 

FOR i: CARDINAL IN [0..8) DO 
FORj: CARDINAL IN [0..8)dO 

IF(i MOD 2 ■ j MOD 2) THEN Display.Gray[ 
window: window, 
box: [place: [ 

x: (offsetWidth + 1 + i*(checkerWidth + 1)), 
y: (offsetHeight + 1 + j*(checkerHeight + 1))], 
dims: [checkerWidth, checkerHeight]]] ; 

ENDLOOP; 
ENDLOOP; 

- put the checkers on the board 

FOR m: CARDINAL IN [0..8) DO 
FOR n: CARDINAL IN [0..8) DO 

bitmap: Defs.Bitmapltems; 
SELECT mydata[m][n]. piece from 

black =» > bitmap <- black; 

blackKing s > bitmap <-blackKing; 

white ■ > bitmap <- white; 

whiteKing = > bitmaps whiteKing; 
ENDCASE = > loop; -no piece here 
Disp[ay.Bitmap[ 

window: window, 

box: [place: mydata[m][n]. place, 
dims: oefs.squareDims], 

address: Defs.GetChecker[bitmap], 

bitmapBitWidth: checkerWidth, 

flags: Dispiay.replaceFlags]; 
IF mydata[m][n]. marked then Dispiay.lnvert[ 

window: window, 

box: [place: mydata[m][n]. place, 
dims: Defs.squareDims]]; 

ENDLOOP; 
ENDLOOP; }; 
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Once an actual game is in progress, areas of the screen 
(checkerboard squares) will gradually become invalid as the 
user moves the checkers around. Thus, the code to move and 
delete checkers requires invalidations and validations. For 
example, the code to delete a piece might look like this: 

DeletePiece: proc[ 

square: Defs.Square, window: window.handle] a { 
IF square ■ nil then return; 
square.piece none; 
window.lnvalidateBox[ 

window, [square.place, Defs.squareOims]]; 
Window. Validate[wi ndow] ; 

}; 

This code assumes that the data type Defs.Square contains fields 
for the tool window, the location of the square in the matrix, 
and the current contents of the square. 

6.3.2.2 Example: FlySwatter 



Here is an example that uses Dispiay.White and Display.Bltmap. 
This example is part of a "Fly Swatter" game that displays flies 
in the body window of an application, turns the cursor into a 
flyswatter, and lets the user swat flies on the screen. 

-Here is part of the interface FlyDefs 
Data: TYPE ■ long pointer to DataObject; 

DataObject: type = record [ 

iterations: cardinal «- 0, - number of times fly has appeared 
numberOfHits: cardinal <- 0, - successful hits 
stopGame: boolean f-TRUE]; - game in progress or not 

-messages stuff 

Key: type ■ {startGame, ...}; 

Get: procedure [key: Key] returns [xstrmg.ReaderBody]; 



-the implementation 
FlySwatterlmpI: program. . . = 
begin 

sysZ: uncounted zone a Heap.systemZone; 
-the width of a "fly" 
FlyBitMapWidth: cardinal = 32; 

-bitmap is 32x 32, so it takes 64 16-bit words to represent a fly. 
WordslnPicture: cardinal = 64; 

IconPictureBlts: TYPE ■ array [O..WordslnPicture) of word; 
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-procedure to start game 
PlayGame: public procedure [ 

body: window.Handle, data: FiyDefs.Data] ■ 

begin 

ticks: Process.Ticks - Process.MsecToTicks[1000]; 
startGame: xstring.ReaderBody <- 
Defs.Get[Defs.Key.startGame]; 

< < Create a temporary area of storage for the bitmap, to 
keep it out of the program's frame. This is the star)dard way 
to allocate space for a bitmap. > > 
bitBuffer: long pointer to IconPictureBits <r- 
space.ScratchMap[1]. pointer; 

~ make the cursor turn into a flyswatter 
newCursorBitMap: UserTermlnal.CursorArray [177776B, ...]; 
swatter: Cursor.Object [[last,7,7], newCursorBitMap]; 
Cursor.Store[@swatter] ; 

"Start out with whole body window white 
Displav.White[bodv.[fO,OLFlvDefs.bodvWindowDims]]; 

-initialize bitBuffer to contain bitmap picture of fly 
bitBuffer t [000007B, 1 74000B. . .]; 

- reset all the data variables 
data. iterations ^0; 
data.numberOfHits ^0; 
data.stopGame <- false; 

-post message telling user that game is starting 
Attention.Post[@startGame]; 

-choose a random location for the fly; store in myBox 
FOR i : CARDINAL IN [O..FiyDefs.iterationsPerGame) 
while not data.stopGame do 

xPos: INTEGER ..random location 

yPos: INTEGER <— ..random location 

myBox: window.Box <— 

[[xPos, yPos], [FlyBitMapWidth, FiyBitMapWidth]]; 

-display the fly in appropriate place 
Dispiav.Bitmapfwindow: body , 
box: mvBox , 

bitmapBitWidth: FiyBitMapWidth , 
address: [bitBuffer, 0,0]]; 

-increment count of number of flies 
data. iterations data. iterations + 1; 

~ wait until its time to do next fly 
Process.Pause[ticks:ticks]; 

ENDLOOP; 

-Game is over, so clear the display, reset the pointer, and 
-print out results of game. 

Dlsplay.White[body,[[0,0],FlyDefs.bodyWindowDims]]; 

data.stopGame «-true; 

Cursor.Set[textPoi nter] ; 

Pri ntStats[body,data] ; 

bitBuffer <-space.Unmap[bitBuffer]; 

end; 
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The first step is to create a bitmap of a flyswatter, and store 
that as the current cursor representation. (Note: Appendix B, 
Icon Editor, discusses how to create bitmaps.) The second step 
is to create a bitmap picture of a fly, and display it periodically 
on the screen. This example displays a fly once a second; a real 
game would make this time variable. We did not include the 
code that decides where to put the fly, since it is incidental to 
the example. 

When the game is over, make the entire body window white, 
and then call PrintStats to print the results of the game. 

You should notice that the procedure PlayGame is not a display 
procedure. When an application wants to display something 
on the screen, the standard method is to update your data 
structures, call invalidate and then call Validate. This will result 
in a call to the application's display procedure, which will 
update the display. 

However, when painting performance is critical, you can paint 
directly to the screen without going through your display 
procedure, as illustrated in this example. This example puts a 
ifly on the screen once every second, so soing regular 
invalidations and validations would be inefficient. 

In fact, there is no display procedure for this example. Even if 
you generally paint directly to the display, you generally still 
need a display procedure to recreate the state of the screen 
when the user moves windows around. However, in this case, 
there is no "current state" of the display to be lost if you cover 
the window and then uncover it, so there is no need for a 
display procedure. 



6.4 LimitProcs and AdjustProcs 



Depending on the kind of information that you display, there 
are times when you want to put some restrictions on the size or 
location of your shell. For example, you might want to ensure 
that the shell always retains a certain minimum size, or that it is 
always on the screen somewhere. You can exercise this kind of 
control with LimitProcs and AdjustProcs. 

A LimitProc gives you control over the size and placement of a 
shell. A LimitProc is of type starWindowSheii.LimitProc: 

StarWIndowShell.LimitPrOC: TYPE = PROCEDURE [ 
SWS: StarWindowShell.Handle, 
box: Window. Box] 
RETURNS [window.Box]; 

The window system will call the LimitProc for a window 
whenever the size or location of the shell is about to change. 
You then have veto or modification rights over the size and 
location of the shell, box is the requested size of the shell; the 
return value is the size that you want the shell to be. A 
LimitProc is thus just a way to potentially change box before 
the actual size change takes place. You set and obtain 
LimitProcs with the following procedures: 
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StarWindowShell.GetLimitPrOC: PROCEDURE [ 
SWS: StarWindowShell.Handle] 
RETURNS [StarWindowShell.LimitPrOc]; 

StarWindowShell.SetLimitProc: PROCEDURE [ 
SWS: StarWindowShell.Handle, 
proc: StarWindowShell.LimitPrOc] 
RETURNS [old: StarWindowShell.LimitPrOc]; 

You should call SetLimitProc from your MakeShell procedure. 
There is a default LimitProc, starWindowSheii.StandardLimitProc, 
that keeps shells on the screen and keeps them from getting 
too small. You only need to write your own limit procedure if 
you have some special needs. 

If your body window display depends on the size of the 
surrounding shell, then you need to write an AdjustProc. An 
AdjustProc is of type StarWindowShell.AdjustPrOC: 

StarWlndowShell-AdjuStProc: TYPE a PROCEDURE [ 
SWS: StarWindowShell.Handle, 
box: Window. Box, 
when: starwindowSheii.When]; 

starWindowSheii.When: TYPE = {before, after}; 

starWindowSheii.GetAdjustProc: procedure [ 
SWS: StarWindowShell.Handle] 
RETURNS [StarWindowSheii.AdjuStProc]; 

StarWindowShell.SetAdjustProc: PROCEDURE [ 
SWS: StarWindowShell.Handle, 
proc: StarWindowShelLAdjustProc] 
RETURNS [old: StarWindowShelLAdjustProc]; 

An AdjustProc will be called both before and after a shell 
changes size, box is the interior size of the StarWindowShell. 
when indicates whether the current call is before or after the 
size changes. Typically, the after case is more interesting, since 
you may have to adjust the display to fit the new box size. 

For more information on LimitProcs and AdjustProcs, see the 
StarWindowShell documentation. 



6.5 Summary 



Using SimplelextDlsplay and Display, an application can 
display arbitrary text and graphics in a body window. Most 
body windows that display information must provide a display 
procedure that can recreate all or part of that display on 
demand. The window implementation will call this procedure 
whenever it needs to redisplay the application's window. The 
only exceptions to this rule are applications like the Fly Swatter, 
which have no state to recreate. 

If an application wants to change its display, it can either just 
display the new information directly to the screen, or it can 
update its data structures to represent the correct information, 
call window.lnvalidateBox to specify that a portion of the screen 
is invalid, and then call window.Validate to force the window 
system to update the display. The latter method is preferred. If 
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you want to display information directly to the screen without 
going through your DisplayProc, you should read the caveats in 
section 50.3 of the Viewpoint Programmer's Guide. 

If the informationthat you display depends on the size or 
location of the shell, then you need to write a 
StarWindowShell.LimitPrOC and/or a StarWindowShell.AdjustProc. 
The LimitProc allows you to exercise control over the location 
of your shell; the AdjustProc allows you to adjust the contents 
display according to the size and location of the shell. 



6.6 Exercise 



Text Window provides a non-editable window for displaying 
text. You display text by selecting an icon (simple document) 
on the desktop and invoking the Load command. If no file is 
currently selected, Load will clear the window. 

Text Window also has a Wrap command that toggles the state 
of the wrapping. When the wrapping is on, the line width will 
be equal to the width of the window (the text will fit the body 
window.) When wrapping is off, the line width will be 
constant, and you will have to make the window bigger if you 
want to see more of the text. Figure 6.2 illustrates the Text 
Window tool with a file loaded in it and wrapping turned on. 
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Figure 6.2 The Text Window tool 



You are to write the user interface for the Text Window and 
implement the Load and Wrap commands. The procedures that 
you will implement are in the template TextExercise.mesa. 
Other files that you will need are Textlmpl.mesa, 
TextDefs.mesa, and Text.Config. 
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Once you have created a body window for an application, you 
need to define its user interface. The last chapter discussed 
how to display arbitrary text and graphics in a body window. 
This chapter discusses how to convert a body window into a 
form window. 

A form window is a body window whose purpose is to display 
the parameters and commands associated with an application. 
Thus, you might want to use a form window if your application 
requires specific user input, commands, and feedback. 

Form windows are also the basis for property sheets, which 
provide a standardized way to examine and change the 
properties of an object. This chapter discusses the facilities of 
the FormWindow interface; the next chapter discusses the 
PropertySheet interface. 



7.1 Overview 



The form window is based on the abstraction of a form, such as 
a personnel form or an income tax form, that has specific 
blanks for the user to fill in. Figure 7.1 illustrates a typical form 
window. 
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Figure 7.1: Form window 



A form window contains form items, which generally consist of 
a keyword, such as the name of a command or parameter, and 
space for the user to fill in values for parameters. The user fills 
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in the appropriate parameters and then invokes a command. 
Here is a list of form item types: 

boolean item A boolean item has two states: on and off (or 
TRUE and false). When the value is true, the item 
is highlighted. 

choice item A choice item has an enumerated list of choices, 
from which the user can select one value at a 
time. A choice item's value is of type 
Formwindow.Choicelndex. 

text item A text item is a user-editable string; its value is 
of type xstring.ReaderBody. 

decimal item A decimal item is a text item that has a value of 
type XLReai.Number. 

integer item An integer item is a text item that has a value of 

type LONG INTEGER. 

command item A command item is an item that has an 
associated procedure. The system calls this 
procedure when the user invokes the 
command. 



tagonlyitem A tagonly item is a string that the user can 
neither select nor edit. 

window item A window item is a window that is a child of the 
form window and can contain anything you 
like. A window item's value isa window.Handle. 



7.2 Creating form windows 



To create a form window, call Formwindow.Create: 

Formwindow.Create: procedure[ 
window: window.Handle, 
makeltems: FormWindow.MakeltemsProc, 
layoutProc: Formwindow.LayoutProc <-nil, 
windowChangeProc: FormWindow.GlobalChangeProc <-nil, 

zone: UNCOUNTED zone <- NIL, 

clientData: long pointer <- nil ]; 

Create takes an ordinary window and makes it a form window. 
Typically, the window parameter will be a body window that 
you created by calling starwindowShell.CreateBody. 

makeltems, layoutProc, and windowChangeProc are call-back 
procedures, makeltems creates the items that you want in your 
form window; layoutProc specifies the desired position of the 
items in the window, and windowChangeProc allows you to 
react when the value of something in the form window 
changes. The following sections discuss each of these 
parameters in detail. There is also an example in section 7.2.4 
that contains a full example of a call to Create. 
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zone is the zone from which FormWindow will allocate storage 
for the items in the form window. If you don't supply a zone, 
FormWindow will use its own private zone. 

clientData is passed to makeitems, layoutProc, and 
windowChangeProc. This parameter is for your own use: if 
there is any additional information that you want to pass to 
your makeitems, layoutProc, or windowchangeProc, you can 
do it via clientData. 



7.2.1 MakeltemsProcs 



The Makeitems parameter to Create is of type 
Formwindow.MakeltemsProc: 

Formwindow.MakeltemsProc: type * procedure [ 
window: window.Handle, -form window 
clientData: long pointer]; -pointer passed to Create 

This procedure allocates the various items that you want to 
display in your form window. The FormWindow interface 
provides a procedure for creating each type of item: 
MakeBooleanltem, MakeChoiceltem, MakeCommandltem,and 
so on. In your Makeitems procedure, you should just call the 
appropriate procedure for each item that you want in your 
form window. 

Obviously, since each type of form item has different 
characteristics, the procedures to make the various kinds of 
form items are slightly different. The following sections 
describe MakeCommandltem, MakeTextltem, and 
MakeChoiceltem; consult the ViewPoint Programmer's Manual 
for the declarations of any of the other MakeXXX procedures. 

The example in section 7.2.4 contains an example of a 
MakeltemsProc. 

7.2.1.1 MakeCommandltem 



Formsw.MakeCommandltem: procedure [ 
window: window.Handle, 
myKey: FormSw.ltemKey, 
tag: xstnng.Reader <-niu 
suffix: xstring.Reader ^NiL, 
visibility: Formsw.Visibility<- visible, 
boxed: boolean <- true, 
readonly: boolean <- false, 
commandProc: FormSw.commandProc, 
commandName: xstnng.Reader]; 

This procedure creates a command item. The first seven 
parameters are common to all the procedures that create form 
items; only the last two are specific to command items. 

window is the form window. (This should be the same as the 
window passed to your MakeltemsProc.) 

myKey is a key that you define for the item. The item key 
uniquely identifies the item. You will need to use this key to 
make calls on other FormWindow procedures. You can use any 
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scheme you want for defining keys, but each item in a given 
form window must have a unique /cey. (An ItemKey is just a 

CARDINAL.) 

tag is text that will appear before (to the left of) the item on 
the same line; suffix is text that will appear after (to the right 
of) the item on the same line. Typically, there is no tag or suffix 
associated with a command item. 

visibility indicates whether the item should be displayed on the 
screen. The default is visible. For information on invisible items, 
see the Viewpoint Programmer's Manual.) 

boxed indicates whether the item should have a box drawn 
around it. 

readonly indicates whether the user can change the value of 
the item. (If an item is readonly, the client can still change the 
value by calling appropriate procedures in the FormWindow 
interface.) 

The last two parameters are specific to a command item. The 
commandName is the name that will appear in the form 
window; invoking this command will result in a call to 
commandProc. A commandProc is of type 
FormWindow.CommandProc: 

Formwindow.CommandProc: type = procedure [ 
window: window.Handle, 
item-.Formsw.ltemKeyl; 

7.2.1.2 Makelextitem 



Formwindow.Makelextltem: procedure [ 
window: window.Handle, 
my Key: FormWindow. Item Key, 
tag: xstring. Reader <- nil, 
suffix: xstring. Reader <- nil, 
visibility: FormWindow.Visi bi I ity <- visible, 
boxed: boolean <- true, 
readonly: boolean «- false, 
width: cardinal, 
initString: xstring.Reader <-nil, 
wrapUnderlag: boolean false, 
passwordFeedback: boolean <-false, 
hintsProc: Formwindow.TextHintsProc *-nil, 
nextOutOfProc: FormWindow.NextOutOfProc ^nil, 
SPECIALKeyboard: BiackKeys.Keyboard f-NiL]; 

The first seven parameters are identical to those in 
MakeCommandltem. 

width is the desired width of the item, in screen dots. 

initString is the initial string (default value) for the text item. 

wrapUnderlag is not yet implemented. 

passwordFeedback indicates that the text should be displayed 
in an unreadable form (asterisks) rather than as normal 
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characters. The correct value of the string is maintained 
internally. 

hintsProc will be called to make a popup hint menu for the 
user. nextOutOfProc will be called when the user presses the 
next key while the input focus is in this text item. This gives the 
client an opportuntity to create more text items. 
SPECIALKeyboard allows clients to make a special keyboard 
available to the user when he is typing into a text field. 

These last three parameters are beyond the scope ofthis course. 
For more information, see the FormWindow documentation in 
the Viewpoint Programmer's Manual. 

7.2.1.3 MakeChoiceltem 



Formwindow.MakeChoiceltem: procedure [ 
window: window. Handle, 
my Key: FormWindow. Item Key, 
tag: xstring. Reader nil, 
suffix: xstring.Reader <-NiL, 
visibility: FormWindow.Visibility <— visible, 
boxed: boolean «- true, 
readonly: boolean <- false, 
values: FormWindow.Choiceltems, 
initChoice: Formwindow.Choicelndex, 
fuiiyDlspiayed: boolean true, 
verticallyDlspiayed: boolean <- false, 
hintsProc: Formwindow.ChoiceHintsProc <-nil, 
changeProc: Formwindow.ChoiceChangeProc «-nil, 
outlineOrHighlight: FormWindow.OutlineOrHlghiight 
highlight]; 

This procedure creates a choice item. A choice item is an 
enumerated list of choices, from which the user selects the 
current value of the item. When the user clicks on a choice, that 
choice becomes the current choice. 

values is the list of all possible choices. It is of typeChoiceltems: 

Formwindow.Choiceltems: type = long descriptor for array 
Formwindow.Choicelndex OF FormWindow.Choiceltem; 

Formwindow.Choicelndex: TYPE s CARDINAL [0..37777B]; 

FormWindow.Choiceltem: type = record [ 

var: select type: FormWindow.ChoiceltemType from 
string ■ > [ 
choiceNumber: Formwindow.Choicelndex, 
string: xstring.ReaderBody], 
bitmap = > [ 
choiceNumber: Formwindow.Choicelndex, 
bitmap: FormWindow.Bitmap], 
wraplndicator ■ > null]; 

FormWindow.Bitmap: TYPE = RECORD [ 

height, width: cardinal, 

bitsPerLine: cardinal, 

bits; Environment.BitAddress]; 

Thus, each choice consists of either a string or a bitmap, and an 
associated Choicelndex. (Chapter 6, Displaying information on 
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the screen, discusses bitmaps in more detail.) You define the 
item indices; the values don't matter, except that each item 
within a given choice must have a unique index. 

For string choices, the FormWindow implementation will copy 
the storage for the string; for bitmap choices, it will not. Thus, 
if you use a bitmap, you must ensure that the bitmap pointer is 
valid for the life of the form window. 

wraplndicator is not really a choice; it allows you to specify 
that the choices should go onto a new line, wraplndicator is 
thus exclusively for formatting. 

initChoice specifies which value should be the initial choice. 

fuiiyDlsplayed indicates whether to display all choices or just 
the current one. If fuiiyDlsplayed a false, the rest of the 
choices are available from a popup menu. 

verticallyDlspiayed indicates whether to display the choices 
vertically or horizontally. This is only important when 
fullyDispiayed is true. 

hintsProc allows you to create a popup hint menu. The default 
creates a hint menu with all possible choices. See the 
FormWindow documentation for details. 

changeProc will be called whenever the choice changes. 
Section 7.2.3 discusses change procedures in more detail. 

outiineOrHlghlight specifies whether to highlight or underline 
the selected item . 

Formwindow.OutlineOrHlghllght: type = {outline, highlight}; 



7.2.2 LayoutProcs 



The second procedure parameter to Create is a LayoutProc, 
which defines the layout of the form items on the screen. The 
layout procedure is of type Formwindow.LayoutProc: 

FormWindow.LayOUtPrOC:TYPE - PROCEDURE [ 

window: window.Handle, 
clientData: long pointer]; 

Unless you explicitly lay out an item, it will not appear in the 
form window at all. If you don't want to write your own layout 
procedure, you can use FormWindow. Def a ultLayout, which 
places each item on a separate line. If you prefer to write your 
own layout procedure, you can use either flexible layout or 
fixed layout. 

Flexible layout allows text, decimal, integer, and window items 
to grow and shrink (and other items to move around 
accordingly) as the user or program changes values of items in 
the form window. Among other things, this kind of layout 
simplifies multinational conversion. Fixed layout, on the other 
hand, does not allow any movement; you specify where the 
items are to go, and they remain there until you explicitly move 
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them. Flexible layout is the preferred method. The following 
sections discuss both methods in detail. 

7.2.2.1 Flexible layout 



A form window with flexible layout consists of horizontal lines 
with zero or more items on each line. Each line may be a 
different height, but should be at least 
Formwindow.defaultLlneHeight to avoid overlap. You can 
control vertical spacing by using appropriate heights for the 
lines. Similarly, you can control horizontal spacing with 
TabStops. The example in Section 7.2.4 uses TabStops; for 
more detail, you will have to consult the FormWindow 
documentation. 

To create a flexible layout, start by calling either 
Formwindow.AppendLlne or FormWindow.lnsertLlne to create a 
line. Once you have a line, you put items on that line by calling 
Formwindow.Appendltem or Formwindow.lnsertltem. The Append 
routines add items after the previously created line or item; the 
Insert routines add items between previously created items or 
lines: 

Formwindow.AppendLlne: procedure [ 
window: window.Handie, 

height: CARDiNAL<-Formwindow.defaultLineHeight] -In pixels 
RETURNS [line:FormWindow. Line]; 

FormWindow.lnsertLlne: procedure [ 
window: window.Handie, 
before: Form window. Line, 

height: cardinal <- Formwindow.defaultLlneHeight] 
returns [line: Form window. Line] ; 

Formwindow.Appendltem: procedure [ 
window: window.Handie, 
item: FormWindow.ltemKey, 
line: FormWindow.Line, 
preMargin: cardinal <-0, 
tabStop: cardinal <-nextTabStop, 
repaint: BOOLEAN <-true]; 

Formwindow.lnsertltem: procedure [ 
window: window.Handie, 
item: FormWindow.ltemKey, 
line: FormWindow.Line, 
beforeltem: FormWindow.ltemKey, 
preMargin: cardinal <-0, 
tabStop: cardinal <- FormWindow.nextTabStop, 
repaint: boolean <-true]; 

Here is an example of a layout procedure using the flexible 
method: 
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LayoutFormltems: FormWindow.LayoutProc = { 
-create first line 
line: Form window. Line <— FormWmdow.AppendLine 

[window: window, 

- height f- defaultLineHeight -]; 
-add items whose keys are 1 and 4 to first line 
FormWindow.Appendltem [ 

window: window, item: 1,line: line]; 
FormWindow.Appendltem 

[window: window, item: 4, line: line]; 
-Create second line 
line <— Formwindow.AppendLine [ 

window: window]; 
-add item whose key is 2 to second line 
FormWindow.Appendltem [ 

window: window, item: 2, line: line]; 
-create third line 

line Formwindow.AppendLine [window: window]; 
-add item whose key is 3 to third line 
FormWindow.Appendltem [ 

window: window, item: 3, line: line]; 

}; 

7.2.2.2 Fixed layout 



With fixed layout, you call Formwindow.SetltemBox to specify 
the exact position of each item : 

Formwindow.SetltemBox: PROCEDURE [ 

window: window.Handle, 
item: FormWindow.ltemKey, 
box: window.Box]; 

window.Box: TYPE = RECORD [place: Window.Place, 
dims: window.Dims]; 

Window.Place: type = UserTerminal.Coordinate; 

Window.Dims: type ■ record [w: integer, h: integer]; 

With this method, all items stay where you put them unless you 
make another call to SetltemBox. Thus, text, decimal, integer, 
and window items will not grow or shrink. This method is 
incompatible with flexible layout: either all layout must be 
flexible, or all layout must be fixed. Here is an example of 
laying out a window using the fixed method: 

LayoutFormltems: FormWindow.LayoutProc = { 
Formwindow.SetltemBox [ 

window: window, item: 1, box: [[10,20], [60,20]]; 
Formwindow.SetltemBox [w 

indow: window, item: 2, box: [[10, 50], [45,20]]; 
Formwindow.SetltemBox [ 

window: window, item: 3, box: [[20,80],[150,120]]; 
Formwindow.SetltemBox [w 

indow: window, item: 4, box: [[70,20], [60,80]]; 

}; 
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7.2.3 ChangeProcs 



The third procedure parameter to Create is a change 
procedure. When the user changes something in the form 
window, you typically need to recognize that change and act 
upon it. There are three ways that you can monitor changes in 
a form window: with a global change procedure, with a local 
change procedure, or with a changed boolean. 

The change procedure that you pass to Create is a global 
change procedure that ViewPoint will call whenever a user or a 
program changes the value of an item in the form window. 

FormWmdow.GlobalChangeProc: type = procedure [ 
window: window.Handle, 
item: FormWindow.ltemKey, 
calledBecauseOf: FormWindow.ChangeReason, 
ciientData: long pointer]; 

FormWindow.ChangeReason: TYPE = {user, client, restore}; 

Whenever the value of any item in the window changes. 
Viewpoint will call your GlobalChangeProc with the key of the 
item that was changed. If more than one item was changed, 
item will be nullltemKey and you will have to use the changed 
boolean (discussed below) to decide which items have 
changed. 

calledBecauseOf specifies the kind of change. (Restore means 
that the client called Form window. Restore to return the form 
window to a former state.) 

You can also associate local change procedures with particular 
kinds of items, such as booleans and choice items. You can 
associate a local change procedure with an item when you 
make the item. (Note: if a window has both a global change 
procedure and a local change procedure, the local one will be 
called first.) 

The third way to keep track is with the "changed boolean." 
Every item that has a value that the user can change (all except 
tag-only, command, and window items) has an associated 
changed boolean. The initial value of this boolean is always 
FALSE. When the value of an item changes, the FormWindow 
implementation sets the boolean to true. You can thus check 
the boolean for a given item to find out if that item has 
changed.You are responsible for setting the boolean back to 

FALSE. 

The FormWindow interface provides procedures that you can 
call to see if any items in the window have changed 
(HasAnyBeenChanged), to see if a specific item has been 
changed (HasBeenChanged), to reset the boolean for an 
individual item (ResetChanged), and to reset all booleans 
(ResetAllChanged). See the FormWindow chapter of the 
Viewpoint Programmer's Manual for details. 
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7.2.4 Example 



Here is an example that creates the application illustrated in 
Figure 7.1. 

DIRECTORY. 

Example: PROGRAM IMPORTS... a { 

Items: TYPE = {checkforvalidity, data, executeQuery, name, 
aliases, born, known Vices}; 

formWindowDlms: window.Dlms «- [450, 250]; 

shellDims: window.Dlms ■ [550, 750];- s/ze of too/ 

name: xstrlng.ReaderBody <-xstring.FromSTRING["Example"L]; 

tabStoplnterval: cardinal b 50; 

context: Context.Type <-Context.UniqueType[]; 

~ Procedures 

--register command in Attention Menu 

Init: PROCEDURE a { 

Attention.AddMenultem [ 
MenuData.Createltem [ 
zone: Heap.systemZone, 
name: @name, 
proc: MakeShell] ]; 

}; 

< < create StarWindowShell with one body window. Make 
body window a form window, and then display shell on 
screen. > > 

MakeShell: MenuData.MenuProc - { 

shell: starWindowSheii.Handle s sta rwindowSheii. Create [ 

name: @name]; 
formWindow: window.Handle <— 
StarWindowShell.CreateBody [ 
sws: shell, 

box: [[0,0],formWindowDims] ]; 
FormWindow.Create [ 

window: formWindow, 

makeltemsProc: Makeltems, 

layoutProc: DoLayout]; 
starwindowSheii.SetPreferredDlms [shell, shellDims]; 
StarWIndowShell.Push [shell]; 

}; 

-create the items in the form window 
Makeltems: Formwindow.MakeltemsProc = { 

fwz: UNCOUNTED ZONE a FormWindow. GetZone[window]; 

-create Check for validity boolean 

BEGIN 

rb: xstring.ReaderBody <- 

xstring.FromSTRING["Check for validity"L]; 
FormWindow.MakeBooleanltem [ 

window: window, 

myKey: Items.checkforvalidity.ORD, 

initBoolean: true, 

label: [string[rb]] ]; 
end; 
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—create Data choice item 

BEGIN 

choiceO: xstring.ReaderBody 

xstring.FromSTRING["NAME"L]; 
choicel : xstring.ReaderBody <- 

xstring.FromSTRING["EMP NO."L]; 
choiceZ: xstring.ReaderBody <- 

xstring.FromSTRING["DEPT."L]; 
tag: xstring.ReaderBody «-xstring.FromSTRING["Data"L]; 
choices: array [0..3) of FormWindow.Choiceltem <- [ 

[string[0, choiceO] ], 

[string[1, choicel] ], 

[string[2, choice2i]]; 
Formwindow.MakeChoiceltem [ 

window: window, 

my Key: items.data.ORD, 

tag: @tag, 

values: DESCRiPTOR[choices], 
initChoice: 0]; 
end; 

"Create command item 

BEGIN 

rb: xstring.ReaderBody <-xstring.FromSTRING[ 

"Execute Query"L]; 
Formwindow.MakeCommandltem [ 

window: window, 

myKey: Items.executeQuery.ORD, 

commandProc: ExecuteQuery, 

commandName: @rb]; 
end; 

-Create first text item. Omit code for other text items, 
-since they are all nearly identical. 

BEGIN 

initString: xstring.ReaderBody <- 

xstring.FromSTRING["William Baumann"L]; 
tag: xstring.ReaderBody <--xstring.FromSTRING["Name:"L]; 
Formwindow.MakeTextltem [ 

window: window, 

myKey: Items. name. ord, 

tag: @tag, 

width: 40, 

initString: ©initString]; 
end; 
...}; 
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-layout the form window with flexible layout 
DoLayout: Formwindow.LayoutProc = { 
lineLeading: CARDINAL ■ 6; -space between lines 
topMargin: CARDINAL = 16; -space before first line 
line: FormWindow.Line; 

-tabs fixed at 50 spaces apart. Line up data, name, 
-aliases, and known vices vertically 
tabChoice: fixed Formwindow.TabStops = 
[f ixed[ tabStoplnterval]]; 

FormWindow.SetTabStops[ 

window: window, tabStops: tabClioice]; 

- Line 1: check for validity boolean and data choice 
line <-Formwindow.AppendLlne [ 

window: window, 
spaceAboveLine: topMargin]; 
FormWindow.Appendltem [ 
window: window, 
item: Items.checkforvalidity.ORD, 
line: line, 

tabStop: 16 /tabStoplnterval, 
preMargin: 16 mod tabStoplnterval]; 
FormWindow.Appendltem [ 
window: window, 
item: Items.data.ORD, 
line: line, 

tabStop: 212 /tabStoplnterval, 
preMargin: 212 MOD tabStoplnterval]; 

- Line 2: blank line 

line <r- FormWindow.AppendLine [ 

window: window, 

spaceAboveLine: lineLeading]; 
-- Line 3: execute query command and name text item 
line <- FormWindow.AppendLine [ 

window: window, 

spaceAboveLine: lineLeading]; 
FormWindow.Appendltem [ 

window: window, 

item: Items.executeQuery.ORD, 

line: line, 

tabStop: 16 /tabStoplnterval, 
preMargin: 16 MOD tabStoplnterval]; 
FormWindow.Appendltem [ 
window: window, 
item: Items.name.ORD, 
line: line, 

tabStop: 201 / tabStoplnterval, 
preMargin: 201 MOD tabStoplnterval]; 

- Line 4: aliases... 
-Line 5: known vices... 

}; 

~ Mainline code 
lnit[]; 

}... 
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7.3 Getting and setting values 



Every item that has a value that the user can change (all except 
tag-only and command items) also has procedures for the 
client to get and set the value. For example, the procedures for 
boolean items are called FormWindow.GetBooleanitemValue and 
Formwindow.SetBooleanltemValue: 

FormWindow.GetBooleanitemValue: procedure [ 
window: window.Handle, 
item: Formwindow.ltemKey] 
RETURNS [value: boolean]; 

Formwindow.SetBooleanltemValue: procedure [ 
window: window.Handle, 
item: FormWindow.ltemKey, 
newValue: boolean, 
repaint: boolean true]; 

For example, to get the value of the Check for validity boolean, 
you could make the following call: 

valid: boolean <-Formwindow.GetBooleanltemValue[ 
window, 

items.checkForValidity.ORD]; 

The procedures to get and set the values of other types are 
nearly identical, except for the type of the value. See the 
Viewpoint Programmer's Marrual if you want more details. 



7.4 Destroying a form window 



FormWindow.Destroy: procedure [window: window.Handle]; 

Destroy destroys all FormWindow data associated with 
window, turning it back into an ordinary window. This 
procedure does not destroy the window itself; it destroys the 
form items within the window. You can also use either 
Formwindow.Destroyltem or FormWindow.Destroyltems to destroy 
individual items without destroying all of the items in the 
window. 



7.5 Summary 



Form windows provide a standardized user interface for 
collecting parameters. 

To create a form window, perform the following steps: 

• Call FormWindow.Create, passing in the following parameters: 

• An existing body window 

• A MakeltemsProc, in which you need to create each item 
that you want to have in your form window. 

• An optional LayoutProc, which specifies where the items 
are to appear in the formwindow. Your layout 
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procedure can use either fixed layout or flexible layout 
If you don't supply a layout procedure, the default is to 
put each item on a separate line. 

• An optional global change procedure, which will be 
called whenever the user changes the value of anything 
in the form window. This allows you to recognize the 
change and act on it. 

For more information on the other procedures in the 
FormWindow interface, see the FormWindow chapter of the 
Viewpoint Programmer's Guide. 



7.6 Exercise 



The exercise for this chapter is the Time Clock application, 
which keeps track of how much time you spend on various 
tasks. Figure 7.2 illustrates this tool. 



I TimeClock 
m 



Print Report | DeleteJob 




Editing 



Reading/answering mail 



Figure 7.2: The TimeClock application 



For each task that you want to keep track of, you create a new 
job, which consists of a title, in-use boolean, and a job number. 
To create a job, type a job number in the appropriate field and 
invoke the "New Job" command. This will create a form field 
for the new job; you can then fill in the name of the job in the 
text item. The tool allows a maximum of 20 possible jobs. 

When you want to start tracking a particular job, you select the 
associated boolean field, and the tool starts keeping track of 
the time that you spend on that job. When you want to stop 
billing a job you can either turn off the boolean or select 
another job. In the figure above, the tool is billing Job 1, but 
not Job 2. The tool can only bill one job at a time; it assumes 
that you can only work on one task at a ti me. 

You can delete an existing job by typing in the job number and 
selecting the "Delete Job" command. This will remove the 
deleted job from the display and delete all data associated with 
the job. 

When you want to see the data, you can select the "Print 
Report" command to print a report of your activities from any 
date to any other date. "Print Report" creates a property sheet 
that contains from-date/to-date fields; simply fill in these fields 
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and select Done and a report will appear on the display. You 
can then copy this report into a document and print it. 

Your assignment is to write the code to generate the form 
window for this tool. The first line of the form window will 
contain 3 commands and an integer (Print Report, DeleteJob, 
NewJob, and jobNumber.) These items are fairly 
straightforward and have corresponding enumerated items in 
the definitions module. 

You also need to create 20 lines, one for each possible job. Each 
of these 20 lines should have a text item, boolean item, and 
integer item. You will have to calculate the itemKey for each of 
these items. In addition, some of these lines may need initial 
values, so you will need to check the context data to see if an 
item has initial values. If the user has created that particular 
job, then the item should have some initial values. 

If a line does have corresponding values in the context data you 
should use those values when creating the form items. If a line 
does not have any values associated with it then you should not 
initialize those values and you should make the line invisible. 
Later, when the user wants to create a new job, our code will 
make these items visible. 

The procedures that you need to implement are in 
TimeClockFormlmplTemp.mesa. The comments in this module 
define what you need to do more completely. 

You will also need the following modules: 

TimeClockDefs 

TimeClockFormlmpI 

TimeClockMsglmpI 

TimeClocklmpI 

TimeClockPSheetlmpI 

TimeClock.config 
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Notes: 
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8. PROPERTY SHEETS 



This chapter describes how to create property sheets, which are 
essentially specialized form windows; the material in this 
chapter is very closely tied to the material in the last chapter. 
However, property sheets also depend on information 
discussed later in the course, such as icons. Thus, there are some 
aspects of property sheets which we delay until later in the 
course. In particular, you will not be implement the aspects 
associated with icons until you have read chapter 15, Icon 
Applications. 

Property sheets allow the user to inspect and modify the 
properties of various objects. For example, paragraph 
properties include margins, justification, and line spacing, and 
printer properties include number of copies and paper size. 
Figure 8.1 shows the property sheet for a mail inbasket 



mttyj.w/w.vMtf.'. 



vff.v^. • /Mf.ww • a^w^.wxw.w. ' 



I Inbasket Properties 



Done I C ancel f Defaults i □ I S 



Mailbox Name Lucille J. Glassn-ianiOSBU North:Xerox 



Icon Label 



Lucille J. Glassman.'OSBU North:Xerox 



On New Mail BEEP FLA5H MESSAGE 



Polling Inten/al 15 Minute 



When Opened 



GET NEW MAIL 



Figure 8.1 : Property sheet 



8.1 Creating a property sheet 



To create a property sheet, you call PropertySheet.Create. 
Typically, you will call this procedure when the user selects an 
icon and presses props, but we do not discuss how to implement 
this until chapter 15. Until then, you can call this procedure 
from anywhere else in your code; in the exercise for this 
chapter, we call it from a command in a tool's header. 
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PropertySheet.Create: PROCEDURE [ 

iPormWindowltems: FormWindow.MakeltemsProc, 
menultemProc: PropertySheet.MenultemProc, 
size: window.Dims, --preferred size of property sheet 
menultems: PropertySheet.Menultems 

PropertySheetpropertySheetDefaultMenu, 
title: xstring. Reader nil, 

placeToDisplay: window.Place <- PropertySheet.nuiiPlace, 
formWindowitemsLayout: FormWindow.LayoutProc ^nil, 
windowAttachedto: starWindowSheli. Handle [nil], 
globalChangeProc: FormWindow.GlobalChangeProc «e-NiL, 
display: boolean ^true, 
clientData: Long pointer <- nil, 
afterlakenDown: PropertySheet.MenultemProc <e- nil, 
zone: uncounted zone «-nil] 
RETURNS [shell: StarWindowSheli. Handle]; 

Some of these parameters, such as MakeltemsProc, LayoutProc, 
and globalChangeProc are identical to the parameters to 
Formwindow.Create. When you are deciding what items to put 
in a property sheet, note that it is conventional to put 
adjectives, rather than commands. For example, "centered" is 
better than "center" and "justified" is better than "justify." 

title is the property sheet title. This should include the word 
"properties" and be in all capitals. For example, INBASKET 
PROPERTIES would be better than Inbasket Properties. 

The rest of this section provides some detail on the 
menultemProc and menultems parameters, and a complete 
example of a call to Create. For information on the other 
parameters, see the PropertySheet documentation in the 
ViewPoir}t Programmer's Manual. 



8.1.1 Menultems 



menultems specifies the menu items (commands) that are 
displayed in the header of the property sheet: 

PropertySheet.Menultems: TYPE ■ PACKED ARRAY 
PropertySheet.MenultemType OF 
PropertySheet.BooleanFalseDefault; 

PropertySheet-Menultemlype: TYPE = 

{done, apply, cancel, defaults, start, reset}; 

PropertySheet-BooleanFalseDefault: TYPE = BOOLEAN*- FALSE; 

MenultemType enumerates the possible commands; 
Menultems specifies a subset of those commands. 

The PropertySheet interface defines two common choices: 

propertySheet.propertySheetDefaultMenu: 
PropertySheet.Menultems ■ [ 

done: true, apply: true, cancel: true]; 

PropertySheet.optionSheetOefaultMenu: 

PropertySheet.Menultems = [start: TRUE, cancel: TRUE]; 
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You can use either of these, if you like. If you want a different 
subset of commands, you will have to use a record constructor 
to set the desired menu items to true. See section 8.1.3 for an 
example of this. 



8.1.2 MenultemsProc 



Viewpoint will call the menultemProc whenever the user 
selects one of the menu items in the header of the property 
sheet. A menultemProc is of type PropertySheet.MenultemProc: 



PropertySheet.MenultemPrOC: TYPE = PROCEDURE [ 
shell: StarWindowShell.Handle, 
formWindow: window.Handle, 
menultem: PropertySheet.MenultemType] 

RETURNS [ok: BOOLEAN <- false]; 



formWindow is the main form window of the property sheet, 
and menultem is the menu item that the user selected. Within 
this procedure, you implement the commands that are in the 
property sheet header. See the next section for an example. 



8.1 .3 Example of PropertySheetCreate 



Here is an example of a call to create a property sheet. This 
code creates the property sheet illustrated in Figure 8.2: 



Mm 



Purge deleted items 



IMMEDIATELY 



NEVER. 



Number of contained items; 24 



Total size:1 027 Disk Pages 



EI 



Figure 8.2: Property sheet for the Wastebasket icon 
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MakePropertySheet: PROC [...] = { 

title: xstring.ReaderBody <-xstring.FromSTRING [ 
"WASTEBASKET PROPERTIES"L]; 

< < Create the property sheet. Have the commands Done, 
Cancel, and Defaults; have MyMenultemProc implement 
those commands. Include a title. > > 

pSheetShell: StarWindowShell.Handle f-PropertySheet.Create[ 
formWindowltems: MakeFWItems, 
menultemProc: MyMenultemProc, 
menultems: [ done: true, apply: false, cancel: true, 

defaults: true, start: false, reset: false], 
title: ©title, 

formWindowltemsLayout: DoLayout]] }; 

-Omit the MakeltemsProc and the LayoutProc, since they are 
- just like those used with form windows. 
MakeFWItems: Formwindow.MakeltemsProc = {... }; 
DoLayout: Formwindow.LayoutProc = {...}; 

< < Called when the user selects a command. If the command 
is Done, then call ApplyAnyChanges to actually make the 
changes; if Cancel, just return OK, since there is nothing to 
change. If Defaults, then call a procedure to set defaults. > > 
MyMenultemProc: PropertySheet.MenultemProc = { 

SELECT menultem from 
done a > 

RETURN [ok:ApplyAnyChanges[formWindowl.ok]; 
cancel ■ > return [ok:TRUE]; 
defaults a > {SetDefaults[formWindow]; 

RETURN [0k:FALSE]}; 

endcase; }; 

< < Update internal information based on the user's change to 
the property sheet This procedure is just a skeleton, because 
the actual procedure relies on information presented in the 
next few chapters. There is a complete example of this kind of 
procedure in chapter 16, Icon Applications. > > 
ApplyAnyChanges: PROc[fw:window.Handle] returns [ok:BOOL] 
a {iFNOTFormwindow.HasAnyBeenChanged[fw] then 

RETURN [0k:TRUE]; 

< < check which items have changed. > > 
FOR myltem: Items in Items do 

ItemKey: FormWindow.ltemKey = myltem. ord; 
iFNOTFormWindow.HasBeenChanged [fw, itemKey] 

THEN loop; 
SELECT myltem from 

purgedeleteditems a > . . 
...;}; 
endcase; 
endloop; i 

RETURN [ok: TRUE]; 

}; 

-procedure called when user invokes defaults command 
SetDefaults: PROC [window: window.Handle] = { 
FormWindow.SetChoiceltem Val ue[ 
window: window, 
item: Items.purgedeleteditems.ORD, 
newValue: 0, repaint: false]; 
Formwindow.Repai nt[wi ndow: wi ndow] ; 

}; 
}... 
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8.2 Linked property sheets 



You can also create linked property sheets, which consist of 
several distinct property sheets that all share the same window. 
The user can only see one property sheet at a time; he selects 
which one to view from a choice item in an additional body 
window, called the link window. The link window remains 
visible at all times, while the main form window displays one of 
the possible choices. 

The Text Property Sheet available with the document editor is 
an example of a linked property sheet. The link window 
contains choices for Character, Paragraph, and Tab Setting 
property sheets; selecting one of them displays the appropriate 
sheet. Figure 8.3 shows a generic linked property sheet with 
three possible property sheets: PSHEET1, PSHEET2, and 
PSHEET3. 



Display 



CHARACTER 



PARAGRAPH 



TAB SETTING 



Units (=J 
Position 



Spaces 



Tab Type 



10 



iiTii. I ; 



Dot Leader 



Dot Leader 



+ 

t 



Figure 8.3: Linked property sheet 



Note that you should only use linked property sheets when you 
have too much information to fit on a single property sheet. In 
general, a property sheet should occupy roughly i of the 
screen. If you find that a property sheet is getting signifcantly 
larger than that, then you should use linked sheets or separate 
sheets or some other method of making the sheet smaller. 

To create a linked property sheet, the first step is to write a 
MakeltemsProc and a LayoutProc for each of the individual 
property sheets. You do not call Create for each individual 
sheet, however. Instead, you call PropertySheet.CreateLlnked. 
This procedure is just like Create except that it has two 
additional parameters: the LayoutProc and the MakeltemsProc 
for the link window: 
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PropertySheet.CreateLinked: procedure [ 

formWindowltems: FormWindow.MakeltemsProc, 
menultemProc: PropertySheet.MenultemProc, 
size: window.Dims, --preferred size of property sheet 
menultems: PropertySheet.Menu Items <- 

PropertySheet.propertySheetDefaultMenu, 
title: xstring. Reader <- nil, 

placeToDisplay: window.Place ^ PropertySheet.nullPlace, 

IFormWindowltemsLayout: FormWindow.LayoutProc ^nil, 

windowAttachedto: starWindowSheli. Handle [nil], 

globalChangeProc: FormWindow.GlobalChangeProc «-nil, 

display: boolean <- true, 

linkWindowltems: FormWindow.MakeltemsProc , 

linkWindowltemsLavout: Formwindow.LavoutProc <-nil 

clientData: Long pointers- nil, 

afterTa ken Down: PropertySheet.MenultemProc <- nil, 

zone: uncounted zone ^ nil] 

RETURNS [shell: StarWindowSheli. Handle]; 

The formWindowltems and the formWindowltemLayout 

parameters should be the appropriate procedures for the 
property sheet that you want to display initially. 
linkWindowltems and linkWindowltemsLayout are the 
corresponding procedures for the link window. 

The layout procedure for the link window is just like any other 
layout procedure. 

The linkWindowltems procedure should create one item: the 
choice item that determines which property sheet is currently 
displayed. You create this item with a call to MakeChoiceltem. 
Recall from the previous chapter that one of the parameters to 
this procedure is a local change procedure that Viewpoint will 
call whenever the user selects a new choice from the choice 
item. This change procedure is responsible for swapping 
property sheets. 

To swap property sheets, call SwapFormWindows: 

PropertySheet.SwapFormWindoWS: PROCEDURE a 
shell: starWindowShell.Handle, -the property sheet 
newFormWindowltems: FormWindow.MakeltemsProc, 
newFormWindowltemsLayout: Form window. LayoutProc nil, 
apply: boolean <- true, 
destroyOld: boolean <-true, 

newMenultemProc: PropertySheet.MenultemProc nil, 
newMenultems: PropertySheet.Menultems <-all[false], 
newTitle: xstring.Reader <-nil, 

newGlobalchangeProc: FormWindow.GlobalChangeProc «-nil, 
newAfterlakenDownProc: PropertySheet.MenultemProc <- 

NIL, 

returns [old: window.Handle]; 

With the exception of shell, apply, and destroyOld, all of these 
parameters are the same as the parameters for a standard call 
to PropertySheetCreate. 

shell is the property sheet, apply specifies whether you want to 
apply any changes to the old property sheet before you 
execute the swap. 

destroyOld determines what happens to the old property 
sheet. If you don't destroy the old one, it is the return 
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parameter. You can then store this old sheet, and call 
SwapExistingFormWindows instead of SwapForm Windows 
the next time you want to create that property sheet. Whether 
you store the old property sheet is up to you; it is a simple 
trade-off of space for time. See the Viewpoint Programmer's 
Mar)ual for the declaration of SwapExistingFormWindows. 

Here is an example that creates a linked property sheet: 

"the items in the link window, plus items in Sheetl. 
Items: TYPE ■ {radix, bOOLEAN, choice, tag}; 

MakePropertySheet: PROC[...l = { 

< < Create the linked sheet with a call to CreateLinked. Sheetl 
is the sheet that is initially displayed. Omit the layout procs and 
Makeltem procedures for the three linked property sheets, 
since they are the same as in earlier examples. > > 
pSheetShell : starWmdowSheii.Handle 

PropertySheet.CreateLinked [ 
formWindowltems: MakeSheetl, 
menultemProc: MakeMenultemsl, 
size: 

llnkWindowltems: MakeLlnkWIndowltems , 
linkWindowltemsLavout: nil ]; -Use default layout 

- for link window 

y. 

< < This is the MakeltemsProc for the link window. It has just 
one item, the choice item that determines which property 
sheet is being displayed. Note the changeProc, which takes 
care of switching the items. > > 

MakeLlnkWindowltems: Formwindow.MakeltemsProc - { 

--declare necessary strings 
sheetl, sheet2, sheet3,tag: xxstring.ReaderBody; 
sheetl <-xstring.FromSTRING ["Sheetl "L]; 
sheetZ <-xstring.FromSTRING ["Sheet2"Li; 
sheets «-xstring.FromSTRING ["Sheet3"L]; 
tag <-XStrlng.FromSTRING ["Current Sheet"L]; 

set up the possible choices as the three strings 
choices: array [0..3) of PormWindow.Choiceltem <- [ 

[string[choiceNumber: 1, string: sheetl]], 

[string[choiceNumber: 2, string: sheet2]], 

[string[cholceNumber: 3, string: sheet3]]]; 

-Create an array of FormWindow.Choiceltem. The tag will be 
-Current Sheet, and the three choices will be Sheetl, 
- Sheet2,and Sheets. 
FormWindow.MakeChoiceltem [ 
window:window, 

myKey:ltems. radix. ORD, --items is the array of form items 
tag:@tag, 

values:DESCRiPTOR[choices], 

initChoice:1 , -choiceNumber of first sheet displayed 
changeProc: ChanqeFormWindow ]; 

}; 
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"Local change procedure that switches property sheets. 
ChangeFormWindow: Formwindow.ChoiceChangeProc = { 
SELECT newValue from 

1 ■> [] «-PropertySheet.SwapForm Windows [ 

shelhpSheetShell, 

newFormWi ndowltems : Ma keSheetl ] ; 

2 ■ > [] f-PropertySheet.SwapForm Windows [ 

shell :pSheetShell, 

newFormWi ndowltems: MakeSheet2]; 

3 ■ > [] <-propertySheet.SwapForm Windows [ 

ShelhpSheetShell, 

newFormWi ndowltems: MakeSheetS}; 

endcase; 

"the MakeltemsProc for the initial property sheet Use 
-messages this time. 

MakeSheetl: FormWindow.MakeltemsProc a { 
-make the boolean item 
FormWindow.MakeBooleanltem [ 
window: window, 
myKey: Items.boolean.ORO, 
tag: Defs.Get[Defs.Key.tag], 
suffix: Defs.Get[Defs.Key.suffixBoolean], 
initBoolean: itemData. boolean, 
label: [string[ 

(Defs..Get[Defs.Key.boolean])]] ]; 
-make the choice item 

BEGIN 

choicel, choice2, choices : xxstring.ReaderBody; 
choices: array [0.3) of Formwindow.Choiceltem <- [ 
[string[choiceNumber: 1, 

string:Defs.Get[Defs.Key.psChoice1]], 
[string[choiceNumber: 2, 

string: Defs.Get[Defs.Key.psChoice2]], 
[string[choiceNumber: 3, 

string: Defs.Get[Defs.Key.psChoice3]]]; 
Formwindow.MakeChoiceltem [ 
window: window, 
myKey: Items.choice.ORD, 
tag : oef s.Get[Def s. Key .tagChoi ce] , 
values: descriptor [choices], 
initChoice: itemData.choice.ORD]; 

end; 

-make the text item 

BEGIN 

Formwindow.MakeTextltem [ 
window: window, 
myKey: Items.tag.ORD, 
tag: Defs.Get[Defs.Key.tagTag], 
width: 20, 

initString: ©item Data. tag ]; 
end; 

}; 
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8.3 Summary 



To create a property sheet, you call PropertySheet.Create instead 
of FormWindow.Create. In addition to a LayoutProc, a 
MakeltemsProc, and a GlobalChangeProc, PropertySheetCreate 
has the following parameters: 

• A menultems record, which specifies the items that are 
to appear in the header for the property sheet. The 
default is for Start and Cancel to appear. 

• A MenultemsProc, which is a call-back procedure to 
implement the commands in the property sheet header. 

You can also create linked property sheets, which are held 
together by a link window. The link window is a form window 
with a choice item, which lists possible property sheets. To 
swap property sheets, you associate a change procedure with 
the choice item in the link window. The change procedure then 
calls PropertySheet.SwapForm Windows to do the swap. 

For more information on the PropertySheet interface, see the 
PropertySheet chapter of the Viewpoint Programmer's Guide. 



8.4 Exercise 



The exercise for this chapter is an extension of the exercise for 
the last chapter. In the last chapter, you wrote the form 
window implementation for the Time Clock application; in this 
chapter, you need to write the property sheet implementation. 
If you didn't do the last exercise, you should go back and read 
the description of how the tool works. 

Invoking the Print Report command creates the property sheet 
illustrated in Figure 8.4. 



II Status Report ^^^^^^P^ Done | (.ancel ini 



Report File PJame SarnpleReport 



Date values should be in the following ranges : 
Month 1-1 2, Day 1 - 31, and Year 1 900 - 9999 



From Month 



To Month 



4 From Dav 



5 To Day 



28 



From Year 



28 To Year 



Figure 8.4: The Time Clock property sheet 



VIEWPOINT PROGRAMMING COURSE 



8-9 



PROPERTY SHEETS 



Your assignment is to write the code to implement this 
property sheet. For a more complete description of what you 
need to do, see the module TimeClockPSheetlmplTemp.mesa, 
which contains a template and comments for the code that you 
need to write. 
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Many applications require specialized interpretation of user 
input. For example, in a game that moves a piece through a 
maze, however, you might want mouse clicks or keystrokes to 
move the piece. This chapter describes the Terminal Interface 
Package (TIP), which provides basic user input facilities. 



9.1 Overview 



There are two named processes that respond to user actions: 
the Stimulus and the Notifier. The Stimulus watches the 
keyboard and mouse for user actions and enqueues them; its 
job is to ensure that no user actions are lost. The Notifier 
dequeues each action and associates it with a window. If the 
action is a mouse click, it goes to the window with the cursor; 
all other actions go to the window with the input focus. 

Once it has determined the correct window for a user action, 
the Notifier decides how to interpret that action by checking 
for the action in the window's TIP tables. A TIP table is 
essentially a giant select statement: the left side of the table 
contains various user actions, and the right side of the table has 
a list of results for each user action. There is typically a chain of 
TIP tables to handle various types of input. 

The Notifier searches all TIP tables associated with a window 
until it finds a match or runs out of tables to check. If it doesn't 
find a match, it discards the action. If it finds a match, it passes 
the corresponding list of results to the application's NotifyProc 
procedure. The NotifyProc then executes some program action 
in response. Figure 9.1 illustratesthis chain of events. 



User presses a keyboard key or mouse button. 



Stimulus process enqueues the action. 



t 

Notifier dequeues action, sends it to a window, and 
then checks the window's TIP tables. If it finds the 
action, the Notifier calls the window's NotifyProc 
with an associated results list. 



The NotifyProc acts on those results. 



Figure 9.1 : Path of user input 
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TIP tables and NotifyProcs thus control the way an application 
responds to user input; this chapter describes how to create 
and modify TIP tables and how to write NotifyProcs. 



9.2 TIP tables 



TIP tables define the way an application responds to user input. 
Since there can be a large number of TIP tables in the system, 
Viewpoint groups TIP tables into a structure based on the type 
of user action that they handle. The TIPStar interface defines 
this structure, which is based on the Placeholder: 

TiPStar.Placeholder: type ■ {mouseActions, keyOverrides, 
softKeys, keyboardSpecif ic, blackKeys, sideKeys, 
backstopSpecialFocus}; 

As their name implies. Placeholders are just categories, not 
actual TIP tables; they are effectively stacks onto which clients 
can add actual TIP tables. There can be a chain of TIP tables 
associated with any placeholder. Figure 9.2 illustrates the list of 
Placeholders, in the order in which they are checked. 



mouseActions 


Point and Adjust 




f 




keyOverrides 


(e.g., PROPS when Props sheet 
is open) 




f 


softKeys 


Top row of keys 




f 




keyboardSpecific 


Keys on physically different 
keyboards 




f 


blackKeys 


The physical keyboard and its 
modifications 




f 


sideKeys 


Keys on either side of main 
keyboard 








f 




backstopSpecialFocus 


All actions not directed to the 
input focus 








NIL 


STOP, UNDO, etc. 



Figure 9.2: The Placeholder tables 



Booting ViewPoint establishes an initial set of tables, called the 
normal tables. The new tables do not replace the placeholders; 
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they are added to the appropriate placeholder "stack", as 
illustrated in Figure 9.3 



mouseActions Placeholder 



NormalMouseTIP 



keyOverrides Placeholder 



softKeys Placeholder 



NormalSoftKeys.TIP 



keyboardSpecif ic Placeholder 



blackKeys Placeholder 



Normal Keyboard.TIP 



sideKeys Placeholder 



NormalSideKeys.TIP 



backstopSpecial Focus Placeholder 



NormalBackstop.TIP 



NIL 



Figure 9.3: The normal tip tables 

The normal TIP tables provide a standard interpretation of user 
actions. When you write an application, one choice is to have 
that application just use the standard TIP tables. However, if 
you want to change the interpretation of certain keystrokes or 
mouse actions, you can add a new table to one of these chains, 
as described later in the chapter. First, however, we discuss the 
syntax of a TIP table and the structure of a NotifyProc. 



9.2.1 TIP table syntax 



In its simplest form, a TIP table is a user-editable file with the 
extension ".TIP." TIP tables are stored in the system catalog. 

The left hand side of a TIP table specifies triggers and enablers. 
A trigger action is an action that has just been dequeued from 
the user action queue; this is the action that caused the 
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Notifier to check the TIP table. Here is part of the relevant 
syntax: 

TriggerTerm :: ■ (Key I mouse I enter I exit) TimeOut 
TimeOut : : ■ empty i before Number I after Number 
Key :: = Keyldent up i Keyldent down 

Thus, the actions that can be in the left hand side of a TIP table 
are mouse movement (mouse), whether the mouse has entered 
or exited the window (enter and exit), time constraints, and key 
transitions. A Keyldent can be any key or a mouse button. (See 
the TIP chapter of the ViewPoint Programmer's Manual for a 
complete list of the key names and for the complete syntax.) 
Timeout specifies a time interval within which the action must 
happen. 

Enable actions are actions that have already happened, or that 
are in progress; enables are generally used to check the current 
state of a key. An enable is thus similar to a while statement. 

The right hand side of a TIP table contains results, which are 
passed to the program's NotifyProc. We discuss results in the 
next section. 

Here is an example of a text version of a TIP table: 

SELECT TRIGGER FROM 

Point Down ■ > 

SELECT TRIGGER FROM 

Point Up BEFORE 200 AND PoInt Down before 200 = > 

SELECT ENABLE FROM 

LeftShlft Down = > coords, ShiftedDoubleClick; 
ENDCASE ■ > COORDS, NormalDoubleClick; 
Adjust Down BEFORE 300 ■ > PointAndAdjust; 
ENDCASE a > COORDS, SimpieCHck; 
endcase; 

This TIP table matches the trigger action Point Down. When 
the left mouse button goes down, remains there no longer 
than 200 milliseconds, and goes down again before another 
200 milliseconds has elapsed, the state of the left shift key is 
checked. If the key is down, the results are coords and 
ShiftedDoubleClick; otherwise, the results are coords and 
NormalDoubleClick. Similarly, If the right mouse button goes 
down less than 300 milliseconds after the left button, then the 
result is PointAndAdjust. If neither of these things happens 
after the left mouse button goes down, then the results are 
coords and SimpleClick. 



9.2.2 Results 



The results passed to a NotifyProc are structured into a linked 
list, of type TiP.Results: 

TiP.Results: type h long pointer to Tip.ResultObject; 



9-4 



viewpoint programming course 



TIP 



Tip.ResultObject: type = record [ 
next: Tip.Results, 
body: SELECTtype: *from 

atom ■ > [a:Tip.ATOM], 

bufferedChar » > null, 

coords a > [place: window. Pi ace], 

int a > [i: long integer], 

key ■ > [key: TiP.KeyName,downUp: TiP.DownUp], 
nop s > [], 

string a > [rb: xstring.ReaderBody], 
time a > [time: System.Pulses], 
endcaseJ; 



For example, Figure 9.4 illustrates one possible chain of results 
for the TIP table discussed above. 



r 






coords: 355, 506 






nil 

atom: ShiftedDoubleClick 







Figure 9.4: A possible results list 



Each element of a results list is an object of type ResultsObject. 
Most of the variants of a ResultObject provide information 
about the current state of the keyboard or mouse. For 
example, coords is the current coordinates of the mouse, key 
represents the state of a particular key, and time measures time 
between user actions. (See the Viewpoint Programmer's 
Manaul for a complete explanation of the variants.) These 
kinds of results are called information results, since they 
encapsulate information about the current state of the world. 

However, a program also typically needs an action result, or 
some indication of what just happened. The most common way 
to convey this information is with an atom, which is essentially 
a unique string. For example, in the previous TIP table we used 
the atoms ShiftedDoubleClick, NormalDoubleClick, 
PointAnd Adjust, and SimpleClick. Each of these are just terms 
that a particular program defines to represent a particular set 
of user actions. 

Thus, a typical results list contains an atom and any necessary 
related information results. The convention is to pass 
"information" results first, and "action" results (atoms) last, so 
that you have the information result available when you 
implement the action. Thus, in the example above, we passed 
the information result coords before the atom. The next 
section contains an example that illustrates how the NotifyProc 
might use these results. 

When you define an atom, you must create it and insure its 
uniqueness with a call to either Atom.MakeAtom or Atom. Make: 
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Atom. Make: procedure [pName: xstring.Reader] 

RETURNS [atom: Atom.ATOM]; 

Atom. Make Atom: procedure [pName:LONG string] 

RETURNS [atom: Atom.ATOM]; 

Make and MakeAtom both return an atom corresponding to 
the character string that you pass in; the only difference 
between them is the type of the argument that you pass in. The 
Atom interface will return the specified atom, creating a new 
one if necessary. 

Here is an example that creates the atoms in the above table. 
Note that we allocate dynamically to keep the storage out of 
the global frame: 

Atoms: PROGRAM a { 

z: UNCOUNTED ZONE a Heap.systemZone; 
atoms: long pointer to AtomRec*- nil; 
AtomRec: type ■ record [ 

PointAnd Adjust, NormalDoubleClick, ShIftedDoubleClick, 

SimpleClick: Atom.ATOM]; 



InitAtoms: procedure = { 

IF atoms m nil THEN atoms <-z.NEw[AtomRec<-[ 
PointAndAdjust: 

Atom . Ma ke Atom [" Po 1 nt An d Ad j u st" L] , 
NormalDoubleClick: 

Atom.MakeAtom["NormalDoubleClick"L], 
ShIftedDoubleClick: 

Atom.MakeAtom["ShiftedDoubleClick"L], 
SimpleClick: Atom.MakeAtom["SimpleClick"L] ] ]; 



InitAtoms; 

}; 



9.3 The NotifyProc 



When the Notifer process recognizes a user action in the left 
side of a TIP table, it passes the associated results list to a 
NotifyProc. The job of a NotifyProc is to interpret the results 
and take appropriate program action. A NotifyProc is of type 
TIP. NotifyProc: 

TIP. NotifyProc: type = procedure [ 

window: window.Handle, results: Tip.Results]; 

Here is a possible NotifyProc for the aboveTIP table: 
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TIPMe: TiP.NotifyProc a { 
place: window.Place; 

< < Note the loop syntax here. This is the standard way to 
use a loop to go through a linked list At the first iteration, 
the local variable input is set equal to the input parameter 
results. Each iteration of the loop looks at input next until it 
reaches the end of the linked list. > > 
FOR input: Tip.Results «- results, input.next until input ■ nil 

DO 

WITH Z: input SELECT FROM 

coords - > place <- z.place; 
atom ■ > SELECT z.a from 

SimpleClick a > Simple[place]; 

NormalDoubleCiick a > NormalDouble[place]; 

ShiftedDoubleClick » > ShiftedDouble[place]; 

PointAnd Adjust ■ > Chord[]; 

endcase; 
endcase; 

ENDLOOP}; 

This procedure loops through the linked list of results. When it 
finds the information result coords, it stores the coordinates 
into the local variable place, and then loops. When it finds an 
action result (atom), it calls an appropriate procedure, passing 
in place when necessary. (This is why it is important to pass 
information results first from the TIP table; if you passed the 
atom first, the value of place would not be available.) 

It is important to realize that the NotifyProc is called once for 
every successful match in the TIP table. The loops in the 
NotifyProc are there because the results list may have more 
than one element (e.g., coords, NormalDoubleCiick), not 
because a series of user actions have been buffered. 



9.4 Incorporating a new TIP table . 



If you want to write your own new TIP table, you also need to 
write code that makes your TIP table available to your 
application. This section describes the steps involved in that 
process. 



9.4.1 Creating the compiled TIP table 



The first step is to translate the text version of the TIP table into 
a program-readable "compiled" TIP table by calling 
Tip.Createlable: 

Tip.CreateTable: procedure [ 
file: xstring.Reader, 

z: uncounted ZONE <- NIL, 

contents: xstring.Reader <-nil] 
RETURNS [table: TiP.Table]; 

TiP.Table: TYPE ■ long pointer to Tip.TableObject; 

Tip.TableObject: type; 
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CreateTable generates a TIP table from the text file file. The 
storage for the table will come from z; if z is nil, then the TIP 
implementation will use its own zone. 

contents is the default contents of file. If CreateTable cannot 
read file or cannot parse file correctly, it will raise InvalidTable: 

TiP.lnvalidTable: signal [type: TiP.TableError, 
message: xstring. Reader]; 

TiP.TableError: type ■ {fileNotFound, badSyntax}; 

The type will be badSyntax if CreateTable could not parse the 
contents of file. RESUMEing the signal will cause TIP to write 
contents string in as the new contents of the file. If the 
contents string doesn't work either, then CreateTable will just 
return nil, without raising the error again. Note, however, that 
the file parameter cannot initially be NIL, because TIP needs 
the name of a file to write the contents string into. 

If the contents parameter is nil, the type wil be fileNotFound: 
the TIP file did not contain the correct information, and there is 
no backup in the contents string. 

When type = badSyntax, the message parameter will contain 
the name of the bad TIP file. 

Here is an example of calling CreateTable: 



"declare strings for the title of the . TIP file ar\d its conterits 
flleName: xstring.ReaderBody <~ 

xstring.FromSTRING ["MyTipFile"L]; 
contents: xstring.ReaderBody ^ xstring. FromSTRING[" 

SELECT TRIGGER FROM 

S Down - > Turn Left; 
D Down ■ > TurnRight; 
K Down = > Forward; 
LDown ■ > Fire; 
endcase..."L]; 

-create the compiled version. 
table: TiP.Table <-Tip,CreateTable[ 
file: @fileName, 

contents: ©contents! TiP.lnvalidTable = > resume]; 

IF table = nilthen{ -bad contents string 

error: xstring.ReaderBody xstring.FromSTRING [ 

"Problem parsing "L]; 
Attention.Post[@error] ; 
Attention.Post[@fileName] }; 



This example will parse the contents of fileName and generate 
the file fileName.TIPC. If there is something wrong with file, 
CreateTable will raise InvalidTable, which we resume. The 
RESUME writes the contents string into file and reparses it. If the 
contents string doesn't work either, then CreateTable does not 
raise the signal again; it just returns nil. (This means that the 
RESUME will not cause an infinite loop.) Thus, we must check for 
NIL after the call to CreateTable. Since we provide a contents 
string, the error type fileNotFound will never be raised. 
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9.4.2 Associating tables and NotifyProcs 



Once you have a table and a NotifyProc, you need to associate 
them with your application. (If you have just a NotifyProc, and 
don't need your own TIP table, you can just pass the NotifyProc 
as a parameter to CreateBody, and you don't need to worry 
about any of this.) 

To associate a window, a table, and a NotifyProc, you call 
SetTable And NotifyProc: 

TiP.SetTableAndNotifyProc: procedure [ 
window: window.Handle, 
table: TiP.Table^ NIL, 
notify: tip. NotifyProc <- nil]; 

This procedure tells the TIP interface about the existence of 
your application's window, and associates a table and 
NotifyProc with it. If you want your application to use only 
your TIP table, and not any of the standard tables, you pass in 
your own table as table. 

If, however, you want your appliation to recognize the 
standard TIP tables, as well as your own new special TIP table, 
then you should obtain the head of the list of standard tables, 
and use that value as table. To obtain the head of the table list 
(the mouseActions placeholder), call TiPStar.NormalTabie: 

TIPStar.NormalTable: procedure returns [Tip.Table]; 

Calling SetTableAndNotifyProc with the head of the tables list 
associates your window with the standard set of TIP tables, and 
registers your NotifyProc. However, you still have to insert your 
TIP table somewhere in the tree of tables. To do this, you call 
TiPStar.PushTable: 

TiPStar.Pushlable: procedure [TiPStar.Placeholder,TiP.Table]; 

PushTable places the new table directly after the specified 
placeholder, without removing any of the existing tables. 
Figure 9.5 illustrates the effect of pushing a new table 
(NewTableA.TIP) onto the mouseActions placeholder. 



mouseActions Placeholder 


► 


NewTableA.TIP 








r 


keyOverrides Placeholder 


< — 


NormalMouse.TIP 



Figure 9.5: Pushing NewTableA onto mouseActions 



Several different calls to PushTable will result in a stack of 
tables "hanging" from the Placeholder. The first table in the 
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chain will be the last one added. Figure 9.6 illustrates the effect 
of pushing a second new TIP table onto mouseActions. 



mouseActions Placeholder 


► 


NewTableB.TIP 








f 






NewTableA.TIP 







1 


r 


keyOverrides Placeholder 


< — 


NormalMouse.TIP 



Figure 9.6: Pushing NewTableB onto mouseActions 

Note: If you want to replace the old tables, rather than just add 
a new one, you can call TiPStar.StoreTable instead of PushTable. 
See the TIPStar chapter of the ViewPoint Programmer's manual 
for details. 

The net effect of all of this is that your new table is not part of 
the standard TIP chain, and that your application is now a 
standard TIP client. When the user is not using your 
application, however, you should remove your TIP table from 
the tree so that your changes do not apply to all other 
applications as well. (Of course, if you want to change the 
interpretation of keystrokes for all applications, you can just 
call PushTable and leave it that way.) 

You remove the table at the top of a particular placeholder 
with PopTable; 

TiPStar.PopTable: procedure lTiPStar.Placeholder,Tip.table]; 

One standard approach is to call PushTable when the mouse 
enters your window, and PopTable when it exits the window; 
the example in the next section illustrates this. 



9.2.3 Input focus 



The Notifier directs mouse actions to the window containing 
the cursor, and keystrokes to the window containing the input 
focus. Thus, if you want your window to be able to accept 
keystrokes, you must make your application control the input 
focus by calling SetlnputFocus: 

Tip.SetlnputFocus: procedure [ 
w: Window. Handle, 
takeslnput: boolean, 
newlnputFocus: LosingFocusProc <-nil, 
clientData: long pointers- nil]; 
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Tip.LosingFocusProc: type = procedure [ 
w: window.Handle, data: long pointer]; 

SetlnputFocus makes your window the input focus; if you want 
your window to take type-in, you should set takeslnput to 
TRUE. When you are about to lose the input focus, Viewpoint 
will call your LosingFocusProc; at this point, you can do any 
sort of clean up that you need to do, such as calling 
TIPStar.PopTable. 



9.2.4 Example 



Here are the relevant portions of a program that creates its 
own TIP table and NotlfyProc. 

TIPExampielmpI : program . . . = { 

- Declare global vars and types 

zone: uncounted zone <-Heap.Create [initial: 4]; 

context: Context.Type <-Context.UniqueType[]; 

atoms: long pointer to AtomRec <- nil; 

AtomRec: type ■ record [ 

enter, exit, mouse, pointDown, pointMotion, pointUp: 

Atom.ATOMl; 
"initialization proc called from the mainline code 
Init: PROC a { 

commandName: xstring.ReaderBody ^ 
xstring.FromSTRING["TIPExample"Ll; 

Attention.AddMenultem [ 
MenuData.Createltem [ 
zone: sysZ, 

name: ©commandName, 
proc: MenuProcl ] ; 
InitAtoms; }; 

--Initialize atoms; called from Init 

InitAtoms: procedure = { 

IF atoms « NIL then atoms <-z.NEw[AtomRec<-[ 
enter: Atom.MakeAtom["Enter"L], 
exit: Atom. Make Atom [" Exit" L], 
mouse: Atom.MakeAtom["Mouse"Ll, 
pointDown: Atom.MakeAtom["PointDown"L] , 
pointMotion: Atom.MakeAtom["PointMotion"L]. 
pointUp: Atom.MakeAtom["PointUp"L] 1 ]; 

}; 
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MenuProc: MenuData.MenuProc a { 
name: xstring.ReaderBody <— 

xstring.FromSTRING["TIPExample"L]; 
data: oefs.Data <-nil; 
tipFile: xstring.ReaderBody <- 

xstring.FromSTRING["TIPExample.TIP"L]; 

"This string represents the contents oftipFile. 
contents: xstring.ReaderBody ^xstring.FromSTRING[" 

SELECT TRIGGER FROM 

MOUSE = > SELECT ENABLE FROM 

Point Down ■ > coords, PointMotion; 
endcase; 

EXIT = > coords. Exit; 

enter = > COORDS, Enter; 

Point Down = > coords, PointDown; 

Poi ntU p = > coords, Poi ntU p; 

ENDCASE. .."L]; 

-- Create the TIP table 

table: Tip.Table <-TiP.CreateTable[ 

file: ©tipFile, contents: @contents!Tip.lnvalidTable = > 
resume}]; 

IF table a NIL THEN { 

error: xstring.ReaderBody <- 

xstring.FromSTRING["Bad syntax in TIPtable"L]; 
Attention.Post[@error] ; 
return}; 

~ Create the StarWindowShell, body window, etc. 
shell f-starWindowSheiLCreate [name: @name]; 
body: window.Handle <-starWindowSheii.CreateBody [ 

sws: shell, 

box: [ place: [0,0], 

dims: oefs.bodyWindowDims ]]; 
-(Set up the form window, pop up menus, ; allocate 
- context, etc.) 

< < Make application a TIP client and have it use the 
standard tables. Any actions that newtable does not handle 
will thus be checked against normal TIP tables. > > 
TiP.SetTableAndNotifyProc [ 

window: body, 

table: TiPStar.NormalTable[], 

notify: MyNotifyProc]; 

StarWindowShell.Push [shell] }; 
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- Handle user input 
MyNotifyProc: TiP.NotifyProc = { 

data: Defs.Oata <-oefs.GetContext[parent]; 

place: window.Place; 

FOR input: TiP.Results <- results, input.next UNTIL input * nil 

00 

WITH z: input select from 
coords a > place <-z.place; 

atom ■ > SELECT Z.a FROM 

pointMotion s > PointMotion[window, data, place]; 
enter ■ > {Tip.SetlnputFocus[ 

w: window, takeslnput: false]; 
TiPStar.PushTable[mouseActions, table]}; 
exit ■ > { 

TiPStar.PopTable[mouseActions, table]}; 
pointDown ■ > 

{data.oldCursorPos place; 
Defs.Seiectltem[window, data]} ; 
pointUp ■ > PointUp[parent, data, place]; 
endcase; 

endcase; -- WITHz: input 
endloop; 

}; 

"The rest of the procedures that do the actual work 



- Main line code 
InitH; 

END. 



9.5 Periodic notif iers 



The Notifier process is important because it responds directly to 
the user. When the user invokes a command, and a process acts 
on that command, that process is "in the Notifier." Only one 
process can be in the Notifier at a given time, and that process 
is guaranteed that the Notifier will not process another user 
action until it has completed. 

This notification mechanism has some important consequences 
for program design. 

First, if you will be processing a command that will take a long 
time to execute, you should fork it from your NotifyProc to 
avoid tying up the Notifier. (If for some reason you must tie up 
the Notifier, you should turn the cursor into an hourglass to 
indicate this to the user.) 

Second, you need to think carefully about which operations 
must be executed from the Notifier to guarantee that there is 
no interference. A good example of such an operation is 
setting the selection: when the user asks to "select" a certain 
object, the process that is responsible for implementing the 
selection (highlighting, etc.) must be guaranteed that no other 
user action (such as one that acts on the selection or changes 
the selection) can interfere. 

When you are responding to a user action (in your NotifyProc), 
you are guaranteed to be in the Notifier, and you have nothing 
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to worry about. However, there are times when you are not 
processing a command, but you still want to have your action 
run from the Notifier to guarantee that there is no 
interference. 

To be able to execute in the Notifier when you are not directly 
processing a user action, you can create a call back procedure 
that will be called from the Notifier at regular intervals: 

Tip.CreatePeriodicNotIfy: procedure [ 
window: window.Handle, 
results: Tip.Results, 
milliseconds: cardinal, 
notlfyProc: TiP.NotifyProc <-nil] 
RETURNS [Tip.PerlodlcNotify]; 

TiP.PeriodicNotify: type [1]; 

CreatePeriodicNotify registers a periodic notify procedure. The 
specified notlfyProc is called from the Notifier with parameters 
window and results once every milliseconds milliseconds, as 
long as no user action notifications are taking place. (If 
notlfyProc is nil, it defaults to the NotlfyProc associated with 
window.) For example, suppose that for some reason you want 
to keep a count of the number of windows on the screen. 
When you want to examine or change this value, you must do 
so from the Notifier: 

count: Atom.ATOM Atom.MakeAtom["UpdateCount"]; 
results: TiP.ResultsObject *- [ 

next: NIL, body: atom[a: count]]; 
notifier: Tip.PerlodlcNotify <-TiP.CreatePeriodicNotlfy[ 

window: window, 

results: ©results, 

milliseconds: 20000]; 

< < The NotlfyProc associated with the window. Since we 
didn't specify a NotifyProc in the call to CreatePeriodicNotifier, 
this one will be used. > > 
MyNotlfyProc: TiP.NotifyProc = { 

Input: Tip.Results; 

FOR Input «- results, results.next do 

WITH Z: Input SELECT FROM 

atom - > 

iFz.a ■ count THEN { "do something 

else{ "do something else 
endcase; 
endloop; 

This example creates a periodic notifier that will be called every 
20,000 milliseconds. The first step is to declare a ResultsObject 
that contains only the atom count. Each time the NotifyProc is 
called, it looks at the value of the count and acts accordingly. 

If you make a call to CreatePeriodicNotify with milliseconds = 
0, then the process runs once and destroys itself. This is known 
as a kamikaze notify proc. 
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9.6 User aborts 



TIP also provides facilities for checking whether the user has 
aborted your application. One way to do this is to associate an 
AttentionProc with your windowby calling 
Tip.SetAttentionProc: 

TiP.SetAttention: proc[ 
window: window.Handle, 
attention: tip. AttentionProc]; 

TiP.AttentionProc: type a proc [window: window.Handle]; 

An AttentionProc is called whenever the user presses the stop 
key. (Note that it is not called from the Notifier.) You associate 
an AttentionProc with your window 

If you don't associate an AttentionProc with your window, the 
system keeps a user abort flag that records whether the user 
has pressed the stop key. You can check that flag at any time by 
calling TiP.UserAbort: 

Tip.UserAbort: proc [window.Handle] returns [boolean]; 

To check if the user has pressed the abort key over a particular 
window, pass in a handle to that window. To check if the user 
has pressed abort anywhere (a global abort), pass in nil. For 
example, code to check for a global abort might look like this: 

IF TiP.UserAbort[NiL] then goto GlobalAbort; 

The abort flag for a window is cleared whenever a non-shift 
key goes down or whenever a notification is sent to the 
window. Once you have looked at the abort flag and acted on 
it, you should call ResetUserAbort to set the flag back to false. 

TiP.ResetUserAbort: proc [window.Handle]; 



9.7 Summary 



The TIP interface provides facilities for translating user actions 
into program actions. The basic scheme is that the Stimulus 
process enqueues user actions and the Notifier process 
dequeues them and directs them to a window. The Notifier 
then looks up the action in a TIP table (or TIP tables) associated 
with the window. If it finds the action, it passes associated 
results to a NotifyProc, which acts on those results. 

To write a new TIP table for an application, you must call 
Tip.Createlabie to create a program-readable version of the TIP 
file, SetTableAndNotifyProc to make your table a TIP client and 
set the NotifyProc, and TiPStar.Pushlable to insert the new TIP 
table into the existing tree of TIP tables. Later, you should call 
TiPStar.PopTable to remove your new table from the tree. 

TIP also provides a periodic riotification mechanism, which 
allows you to provide a call-back procedure that the Notifier 
will call. This allows you to avoid multi-process interference. 
When you are designing your programs, you should think 
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about whether you need to use this technique to avoid multi- 
process interference. 

TIP also provides many other user-input facilities; for more 
information about TIP, see the TIP and TIPStar chapters of the 
Viewpoint Programmer's Mar)ual. Appendix A of the 
Viewpoint Programmer's Manual contains more information 
on the normal TIP tables. 



9.8 Exercise 



The exercise for this chapter is Tank, which plays the classic 
video game of Tank. To play this game, you first decide how 
many enemies you want to have by choosing a value from one 
to five from the Number of Enemies menu. (Note: depending 
on the size of your window, this command may appear in the 
header of the window or it may be in the auxiliary menu for 
the tool.) You can also increase or decrease the speed of the 
tanks by invoking Faster or Slower. 

When you are ready to start playing, invoke Start Game. This 
command draws the "battlefield" and the tanks, as illustrated 
in Figure 9.7. (The octogonal tank is your tank; the others are 
enemy tanks.) 




Figure 9.7: The Tank application 

The battlefield is of fixed size and contains a tank representing 
the user, the tank(s) for the computer, and gray areas that 
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serve as barriers. Any tank can destroy a gray area by shooting 
at it. You can stop the game at any time by invoking Stop 
Game. Otherwise, the game is over when either you have 
destroyed all of the enemy's tanks or you have been destroyed 
by the enemy. 

When you start the game, you have a short amount of time to 
move and or get the first shot in before the other tanks come 
to life. The enemy tanks will always move and shoot in your 
direction. 

You can move your tank with the following keyboard keys: 

s => turn left (rotate counterclockwise) 

d = > turn right (rotate clockwise) 

k = > move forward 

I = > shoot 

Your assignment is to write the code for the following four 
procedures in TankTIPImplTemp: 

InitAtoms initializes the atom used in the NotifyProc 

LostlnputFocus gets called when the tool window loses the 
input IFocus (let the user know this by posting a message in 
the Attention Window.) 

MyNotlfyProc interprets the atoms passed in and calls the 
appropriate procedures. 

SetUpTlpTabie creates the TIP table for user actions. 

You will also need the following modules: 

TankDefs 

TankGraphiclmpI 

TankMsglmpI 

TanklmpI 

Tank.config 
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Notes: 
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NSFILE ATTRIBUTES 



Every ViewPoint volume contains a tree-structured directory of 
files that you can manipulate with the ViewPoint filing system, 
called NSFiling. This chapter and the next three chapters discuss 
Viewpoint files in detail. 



10.1 Content and attributes 



Viewpoint files consist of two types of information: content 
and attributes. The content of a file is the actual data in the 
file. Attributes are pieces of information associated with the 
file that help identify the file, describe its structure or behavior, 
and record other information about the file. Figure 10.1 
illustrates a typical file, with some content and four attributes. 



Name: AddressList.txt 
isDirectory: false 
modlfiedOn: 2-12-86 14:35:46 
sizelnBytes: 10,425 



Robin Miller 

10513 Edgefield Drive 

Adelphi, Maryland 20783 



John Pettey 
Box 2563 

Gettysburg, PA 20604 



Figure 10.1: An NSFile 

This chapter concentrates on specifying and accessing file 
attributes. The next chapter, NSFiling, discusses basic filing 
operations, such as naming, creating, opening, closing and 
deleting files. Chapter 12, Streams, and Chapter 13, 
NSSegment, discuss how to access the content of a file. 



10.2 Interpreted and uninterpreted attributes 



There are two major classes of attributes: interpreted and 
uninterpreted. Interpreted attributes are attributes that have a 
specific meaning to the file system; uninterpreted attributes 
are additional attributes that you define; they do not have a 
specific meaning to the file system. 



Attributes 



Content ^ 



VIEWPOINT PROGRAMMING COURSE 



10-1 



ATTRIBUTES 



The file system defines a wide range of interpreted attributes. 
Not all attributes apply to all files, but you can associate as 
many applicable attributes with a file as you like. Here is a brief 
summary of the major types of interpreted attributes: 

Identity attributes serve to identify a file. Examples of 
identity attributes are name, version, service, and file type. 

File attributes describe basic characteristics of a file. 
Examples of file attributes are checksum, IsDirectory, and 
parentlD. 

Activity attributes record the date and time of significant 
events in the life of a file, and the name of the user on 
whose behalf the event occurred. Examples of activity 
attributes are createdBy, filedOn, modifiedOn, and readBy. 

Size attributes record the size of a file. There are two 
possible size attribues: sIzelnPages and sizelnBytes. 

Access attributes specify the access restrictions of a file. To 
use these attributes, you make access lists and give a 
particular access, such as fullAccess, noAccess, or 
readAccess, to the list. 

Directory attributes apply only to directory files. They 
describe useful characteristics of a directory. Examples of 
such attributes are numberOfChlldren, ordering, and 
defaultOrderlng. 

The above list is not an exhaustive one, but it does cover the 
major kinds of attributes. In general, the file system maintains 
the value of interpreted attributes. For example, when a client 
opens a file with write access, the file system will update the 
modlfiedBy attribute as a side-effect. (You can also explicitly 
change the value of an interpreted attribute via a procedure 
call; see Section 10.4.) 

Unintepreted attributes, on the other hand, do not have a 
specific meaning to the file system. You define and maintain 
your own uninterpreted attributes (also called extended 
attributes), depending on your application. For example, if you 
were implementing a mail system, you might want to use 
extended atttributes to keep information like "sender," "time 
received," "return path" and the like. Section 10.3.2 discusses 
how to define extended attributes. 



10.3 Specifying attributes 



When you create a file, you specify the interpreted attributes 
that you want the file system to maintain for that file. The file 
system will maintain only the attributes you request; it does 
not automatically maintain all possible attributes for all files. 

Attributes are specified with variant records; an NSFiie.Attribute 
can take on a number of different values, depending on the 
variant that you select. When you create a file, you pass an 
NSFiie.AttrlbuteLlst, which is a descriptor for an array of variant 
records representing the attributes that you would like that file 
to have. Here are the relevant type declarations: 
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NSFiie-Attribute: TYPE a machine dependent record [ 
var: select type: NSFile.AttributeType from 
filelD, parentID a > [value: NSFiie.lD], 
checksum a > [value: cardinal], 
type a > [value: NSFiie.Type], 
position a > [value: NSFiie.Position], 
service a > [value: NSFiie.Service], 
ordering = > [value: NSFiie.Ordering], 
accessList, defaultAccessList = > 

[value: NSFiie.AccessList], 
backedUpOn, createdOn, f iledOn, modif iedOn, readOn 

a >[value: NSFiie.Time], 
createdBy,filedBy, modifiedBy, readBy a > 

[value: NSFiie.String], 
name, pathname = > [value: NSFiie.String], 
childrenllniquelyNamed, isDirectory, isTemporary a > 

[value: boolean], 
version, numberOfChildren a > [value: cardinal], 
sizelnBytes, sizelnPages, subtreeSize, subtreeSizeLimit 

a > [value: long cardinal], 
extended = > [type: NSFiie.ExtendedAttributeType, 

value: NSFiie.Words], 
endcase]; 

NSFiie-AttributeList: TYPE a long descriptor for array of 
NSFiie.Attribute; 

Thus, you specify a set of attributes with an array of Attribute 
records, one for each attribute that you want your file to have. 



10.3.1 Specifying interpreted attributes 



Here is some code that specifies a set of interpreted attributes: 

-declare the attributes of interest 
nsFile: Nsstring.string <— 

NSString.StringFromMesaString["file"L]; 
my Version : cardinal «- 1 ; 
myType: NSFile.Type 110010; 

-store them in an array of records 
attributes: array [0..3) of NSFiie.Attribute <- [ 

[name[nsFile]], 

[version[myVersion]] , 

[type[myType]]]; 



This code will produce an array of three Attributes, as 
illustrated in Figure 10.2. 



attributes q 


1 


2 




name 

value:nsFile 


version 

value: myVersion 


type 

value: myType 











Figure 10.2: array of NSFile. Attributes 
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Later, you will need to create a descriptor for this array (an 
NSFiie-AttributeList), and pass the array descriptor to various 
procedures in the NSFlie interface. We discuss how to use these 
attribute lists in the next chapter; for now you only need to 
worry about the syntax of specifying an attribute list. (If you 
are not comfortable with variant record syntax, you might 
want to review the appropriate chapter of the Mesa Language 
Manual or the Mesa Course.) 

You should note the file type attribute. All NSFiles must have a 
file type, which is a long cardinal. Each distinct application has 
a distinct file type; files with similar function or multiple 
instances of an application use the same type. A file type is thus 
an important identity attribute. (You obtain a file type for a 
new application from the Xerox filing group.) 



10.3.2 Specifying extended attributes 



The last variant in the declaration of NSFiie.Attribute is 
extended, which allows you to declare extended attributes. An 
extended attribute is a record with two fields: type and value. 

A type is j ust a long cardinal: 

NSFiie.ExtendedAttributeType: TYPE = long cardinal; 

A type is a unique identifier for a particular extended attribute. 
All attributes, both interpreted and uninterpreted, have a 
unique attribute type. An attribute type identifies a particular 
attribute, much as a file type identifies a particular file. You 
typically don't need to be aware of the type of an interpreted 
attribute, since interpreted attributes have names, but you do 
need to be aware of the attribute type for an extended 
attribute, since extended attributes do not have names. An 
attribute type is the only way to distinguish among different 
extended attributes. 

The value of an extended attribute is the actual attribute 
information. The value is stored in an encoded form. NSFile 
provides procedures that encode/decode booleans, long 

CARDINALS, INTEGERS, LONG INTEGERS, NSStrings, and 

NSFile. References. Thus, when you want to store an extended 
attribute, you need to call the appropriate encoding 
procedure, and when you want to examine an extended 
attribute you need to call a decoding procedure. For example, 
the procedures to encode and decode cardinals look like this: 

NSFile.Words: TYPE ■ LONG descriptor FOR ARRAY OF unspecified; 

NSFiie.EncodeCardinal: procedure [c: cardinal] 
RETURNS [NSFile.Words]; 

NSFiie.DecodeCardinal: procedure [NSFile.Words] 
RETURNS [c: cardinal]; 

Here is a code segment that stores two extended attributes, a 
LONG STRING and a cardinal: 
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String Attribute: NSFiie. Extended Attri buteType ■ 42332; 
cardinalAttribute: NSFiie.ExtendedAttributeType ■ 23231; 
myString: NSString.String ^ 
NSString.StringFromMesaString["aString"L]; 
myCardinal : cardinal <- 99; - arbitrary values 

-store the encoded values for string and cardinal into 
--the records, and create an array of the records. 
newAttributes: array [0..2) of NSFiie. Attribute <- [ 
[extended[ 

type: string Attribute, 
value: NSFile.EncodeString[myString]]], 
[extended[ 

type: cardinalAttribute, 

value: NSFiie.EncodeCardinal[myCardinalll]]; 

This code creates an array of attribute records, as illustrated in 
Figure 10.3. (Note that the figure shows the actual values for 
the attributes, whereas they are actually stored in an encoded 
form.) 



newAttributes o 1 



extended 


extended 


type: 42332 


type: 23231 


value: aString 


value: 99 



Figure 10.3: array of NSFiie. Attributes 

The attribute types in this example are arbitrary. You can 
choose any value you like for an extended attribute type, as 
long as it does not conflict with any other attribute type (either 
interpreted or uninterpreted). Typically, you should consult 
other members of your group to see if they have a standard 
strategy for allocating such types. The range of interpreted 
attribute types is documented in the Filing Programmer's 
Manual. It is good practice to define extended attributes in an 
interface so that you can access them from other modules. 



10.4 Getting interpreted attributes 



The NSFiie interface also provides procedures that allow you to 
inspect and modify attributes of a given file. To retrieve 
attributes, call NSFile.GetAttributes; to set new attributes, call 
NSFiie.ChangeAttributes: 

NSFile.GetAttributes: procedure [ 
file: NSFiie.Handle, 
selections: NSFiie.Selections, 
attributes: NSFiie.Attributes, 
session: NSFile.Session <-NSFiie.nullSession]; 
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NSFiie.ChangeAttributes: procedure [ 
file: NSFiie. Handle, 
attributes: NSFiie.AttributeList, 
session: NSFiie.Session <-NSFiie.nullSession]; 

file is a file handle, which is just a way to specify and access a 
particular file; we discuss file handles in the next chapter. 

selections specifies the attributes of interest, and attributes 
provides the storage for those attributes. The following 
sections provide a detailed explanation of the selections, 
attributes, and session parameters, as well as a complete 
example illustrating both of these procedures. 



10.4.1 Selections 



The selections parameter is of type NSFiie.Selections: 

NSFiie. Selections: TYPE s record [ 

interpreted: NSFiie.lnterpretedSelections 

NSFiie. nolnterpretedSelections, 
extended: NSFiie.ExtendedSelections «- 

NSFiie. noExtendedSelectlons]; 

NSFiie.lnterpretedSelections: TYPE « packed array 
NSFiie.AttributeType of NSFiie.BooleanFalseDefault; 

NSFiie.AttributeType: type = machine dependent {checksum, 
childrenUniqueiyNamed, createdBy, createdOn, f ilelD, 
isDirectory, isTemporary, modifiedSy, modifiedOn, name, 
numberOfChildren, ordering, parentID, position, readBy, 
readOn, sizelnBytes, type, version, accessList, 
defaultAccessList, pathname, service, backedUpOn, f iledBy, 
f iledOn, sizelnPages, subtreeSize, subtreeSizeLimit, 
extended}; 

NSFiie.BooleanFalseDefault: TYPE s boolean <- false; 

This parameter specifies the attributes that you want to 
retrieve. As illustrated in Figure 10.4, a Selections record 
contains an array of booleans corresponding to the possible 
interpreted attributes and a descriptor for an array of 
extended attributes. (For now, ignore the extended attributes; 
section 10.5 discusses how to retrieve extended attributes.) 



interpreted 



FFFFFFFFFFFF 



extended 



ARRAY DESCRIPTOR 



Figure 1 0.4: An NSFiie.Selections record 
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To show interest in particular interpreted attributes, you set 
those attributes to true in the array. GetAttributes will retrieve 
those attributes and store them in the attributes parameter. 



10.4.2 Attributes 



The attributes parameter to GetAttributes is of type 
NSFiie.Attributes: 

NSFiie-Attributes: TYPE ■ long pointer to 
NSFiie . Attr i butes Record ; 

NSFiie-AttributesRecord: TYPE a record [ 
filelD: NSFile.lD, 
service: NSFiie.Service, 
name: NSFiie.String, 
pathname: NSFiie.String, 
version: cardinal, 
checksum: cardinal, 
type: NSFiie.Type, 
isDi rectory: boolean, 
isTemporary: boolean, 
parentID: NSFile.lD, 
position: NSFiie.Position, 
backedUpOn: NSFiie.Time, 
createdOn: NSFiie.Time, 
filedOn: NSFiie.Time, 
modifiedOn: NSFiie.Time, 
readOn: NSFiie.Time, 
createdBy: NSFiie.String, 
filedBy: NSFiie.String, 
modifiedBy: NSFiie.String, 
readBy: NSFiie.String, 
sizelnBytes: long cardinal, 
sizelnPages: long cardinal, 
accessList: NSFiie.AccessList, 
defaultAccessList: NSFiie.AccessList, 
ordering: NSFiie.Ordering, 
childrenllniquelyNamed: boolean, 
subtreeSizeLimit: long cardinal, 
subtreeSize: long cardinal, 
numberOfChildren: cardinal, 
extended: NSFiie.ExtendedAttributeList]; 

The purpose of the attributes record is to provide storage for 
the attributes being retrieved. GetAttributes will copy the 
specified attributes into your attributes record; you can then 
do anything you like with those attributes. 

The attributes parameter to SetAttributes is of type 
NSFiie.AttributeList, which is a descriptor for an array of 
attributes. (See section 10.3.) Be careful to distinguish among 
these data types, which all have similar names. 



10.4.3 Sessions 



Before it can use the file system, a client must log on via the 
Authentication Service. (Note that it is actually the user who is 
authenticated, not the client.) Once the client has been 
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authenticated, the file system establishes a session, which is 
identified by a session handle. The file system returns the 
session handle to the client, which can then use the session 
handle to identify itself in future calls to the file system. 

Logging in to Viewpoint establishes a default session. The filing 
system will use this session in all subsequent filing operations 
unless you specifically request a different session handle. In the 
declaration of GetAttributes, session has a default value of 
nullSession. This default is really the default session, and not a 
null session. In this chapter we use only the default session 
handle; for more information on sessions, see the Filing 
Programmer's Manual. 



10.4.4 Storage management 



Another thing you need to know about GetAttributes is that t 
allocates storage from the system zone. Thus, you need to call 
NSFiie.FreeAttributes after a call to GetAttributes to release 
that storage. The example in the next section illustrates this. 



1 0.4.5 Example of GetAttributes and SetAttributes 



Here is an example that obtains a file's attributes and then 
changes the file's name and version number. 

newVersion: cardinal; 
newName: NSString.String <- 

NSString.StringFromMesaString["newNameForFile"L]; 
fileHandle: NSFile.Handle <- --GetF/7eHanc//eSomeHow; 

-storage for old attributes being retrieved 
m vAttri butes : NSFile. Attri butesRecord ; 
-storage for new attributes 
attri buteArray: array [0..2) OPNSFile.Attribute; 
-create a selections record and set the ones we want to TRUE 
selections: NSFile.Selections s [Interpreted: [ 
name: true, version: true]]; 

NSFiie.GetAttributes f 
file: fileHandle, 

selections: selections, -- select name and version only 
attributes: ©myAttri butes]; - retrieved attributes 

-Put the new attributes in attributeArray 
newVersion <-myAttrlbutes.verslon + 1; 
attributeArray <— [name[newName], versionfnewVersion]]; 
-store the new attributes 
NSFiie.ChanqeAttrlbutes [flle: fileHandle, 
attributes: DESGRiPTOR[attrl buteArray ]]; 

NSFile. FreeAttri butes r@m vAttrl butes] : -important! 

The first step is to set up the parameters to GetAttributes. 
myAttrlbutes is the storage for the attributes being retrieved, 
and selections specifies the attributes of interest. Figure 10.5 
illustrates these data structures. 
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myAttributes 



filelD: 

service: 

name: 

pathname: 

version: 

checksum: 

type: 



selections 



interpreted 



name version 



F 




T 


F 


F 


F 


F 


F 


F 



extended nil 



Figure 10.5: selections and myAttributes 



The call to GetAttributes will store the specified attributes in 
myAttributes, as illustrated in Figure 10.6. 





myAttributes 


filelD: 






service: 






name: fileName 






pathname: 






version: 3 






checksum: 






type: 







Figure 10.6: After the call to GetAttributes 



The next step is to look at the old version number, update it, 
and then store new attributes with a call to SetAttributes. The 
attributes parameter to SetAttributes is a descriptor for the 
array of attributes illustrated in Figure 10.7. 



attributeArray 0 



name 


version 


value:newName 


value: newVersion 



Figure 10.7: attributeArray 
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The final step is to call FreeAttributes. Although myAttributes, 
selections, and attributeArray all come from the local frame 
and will go away when the procedure returns, GetAttributes 
allocates string items from the systemZone and places just a 
pointer to the string in the Attributes Record. Thus, you need to 
call FreeAttributes to free this storage from the systemZone. 



10.5 Getting extended attributes 



You can also call GetAttributes to retrieve extended attributes. 
With extended attributes, the selections parameter is a 
descriptor for an array of attribute types, rather than an array 
of booleans. (See §10.4.1 for the declaration of Selections.) 

NSFiie.ExtendedSelections: TYPE = long descriptor for array 
CARDINAL OF NSFlle.ExtendedAttributeType; 

Looking at the value of the attributes once you have retrieved 
them is also a little more complicated with extended attributes, 
since the values are encoded. You need to search for the 
desired extended attribute type and then call a decoding 
procedure to extract the corresponding value. For example: 

string Attribute: NSFlle.ExtendedAttributeType = 42332; 
cardinalAttributel: NSFlle.ExtendedAttributeType a 23231; 
cardinaiAttribute2: NSFiie.ExtendedAttributeType a 2222; 
myString: NSString.String; 
flrstCardinal, secondCardinai: cardinal; 

--used for specifying selections of interest 

attr: array [0..3) of NSFlle.ExtendedAttributeType <- 

[stri ng Attr i bute, ca rd i na I Attri bute1 , ca rd i na I Attr i bute2] ; 

storage for attributes being returned 
attri butes : NSFiie. Attri butesRecord ; 

flleHandle: NSFiie.Handle < — Get File Handle Somehow; 
NSFiie.GetAttributes[ 
file: fileHandle, 

selections: [extended: DESCRiPTOR[attr]], 
attributes: ©attributes]; 

~ get the values from the extended attributes array by 
-searching for for the attribute type. 
FORc: CARDINAL IN [O..LENGTH[attributes.extended]) do 
SELECT attri butes.extended[c] .type from 
stri ngAttri bute = > myString «- 

NSFiie.DecodeString[attributes.extended[c]. value 
Icourier. Error » > continue] -- decoding error 
cardinalAttributel =>flrstCardinal «— 

NSFiie.DecodeCardinal[attributes.extended[c].value 
Icourier.Error a > continue]; 
cardinalAttribute2 = > secondCardinai 

NSFiie.DecodeCardinal[attributes.extended[c].value 
Icourier.Error a > continue]; 
endcase; 
endloop; 



10-10 



VIEWPOINT programming COURSE 



ATTRIBUTES 



The first step is to create tine array attr, which contains the 
attribute types for the extended attributes of interest, and an 
attributes record, which provides storage for the attributes. 

Next, we call GetAttributes, passing in a descriptor for the 
array of attribute types, and the attributes record. The call to 
GetAttributes will store the specified attributes in the 
attributes record, as illustrated in Figure 10.8. 





attributes 


fllelD: 






service: 






name: 






extended: 






type: 42332 






value: encoded string 






extended: 






type: 2222 






value: encoded cardinal 






extended: 






type: 23231 






value: encoded cardinal 







Figure 10.8: Attributes record 



Since the value field is encoded, you cannot directly access the 
value of an extended attribute; you need to use decoding 
procedures. Thus, the next step is to loop through the 
extended attributes in attributes and match the attribute type 
to string Attribute, cardinalAttributel, or cardinalAttribute2. If 
there is a match, call the appropriate decoding procedure to 
extract the actual value of the extended attribute. (Note: The 
loop is necessary because NSFiling does not guarantee that the 
attributes will be stored in the order specified in selections.) 

You should note the catch phrase for courier.Error in the 
decoding procedures. This catch phrase is used to catch several 
errors, such as using a decoding procedure that is not 
appropriate for the encoded information. To protect yourself, 
you should always catch this error and continue. 



10.6 Summary 



NSFiling attributes contain various pieces of information about 
a file. Attributes are distinct from content, which is the actual 
data in a file. The file system defines a large number of 
interpreted attributes and also allows you to define your own 
extended attributes. 

Attributes are represented by variant records. To specify a set 
of attributes, you create an array of variant records: each 
record represents one attribute. You can then use this array to 
change the attributes for an existing file, to identify an existing 
file or create a new file. This chapter described how to set new 
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attributes for an existing file; the next chapter describes how 
to create new files and find existing files. 

You can specify extended attributes by defining an attribute 
type and an associated value. If you use extended attribute 
types, you have to call encoding and decoding procedures to 
store and record the value of the attribute. 

If you want to access or change a file's attributes, you can call 
NSFiie.GetAttributes. To call this procedure, you need to pass a 
selections parameter that specifies the attributes of interest, 
and an attributes parameter that provides storage for the 
attributes being retrieved. 



10,7 Exercise 



The exercise for this chapter is an application called Music Man. 
This application allows you to write music by adding notes to a 
scale. When run, this application registers the command 
"Music Man" in the Attention Menu; invoking this command 
displaysthe window illustrated in Figure 10.10. 




S2. 



A 



J 



8 



± 
t 



Figure 10.9: The Music Man application 



To add a note, select the desired note, hold down Point, and 
choose a location for the note. The note will track the cursor, so 
you can move the mouse until you reach the right place on the 
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Staff. Releasing Point will add the note to the staff and include 
it in the application's data structure. 

To delete notes, select the "none" choice, move the cursor over 
the desired measure and begin clicking Point. This will 
highlight the notes one at a time. Pressing the delete key when 
a note is video-inverted will remove the note. 

After you have finished editing a page of music you can create 
an Interpress master from the display or you can store the 
music in a file. To make an Interpress master, specify a file and 
select the "Make IP Master"command. To store your music, 
specify a file and select "Store"; to load an existing file select 
"Load". The file that you load can be either on the desktop or 
in the system folder. If the file is on the desktop, you can select 
it instead of typing the file name. 

We have written most of the code for this application. You 
need to write procedures that store and retrieve extended 
attributes. The extended attributes for this application contain 
the number of notes (or other objects) contained in each 
measure of music. The procedures that you will implement are 
called GetExtended Attributes and StoreExtendedAttributes. 

GetExtended Attributes takes a file handle and returns the 
extended attributes in an array. All of the extended attributes 
are cardinals and their NSFiie.ExtendedAttributeTypes are 
specified by the subrange ExtendedSubrange. Thus you should 
get all the extended attributes in the range 
ExtendedSubrange, decode them as cardinals and return them 
in the specified array. 

We have written some of the code in StoreExtendedAttributes 
(so you do not have to understand the details of the data 
structure). You just need to encode the count for each measure 
and associate it with the proper extended attribute type (this is 
well documented within the procedure). Lastly, you need to 
call NSFiie.ChangeAttributes to store the new extended values 
in the file. 

These two procedures are in the module 
MusicFilelmplExerciseA.mesa. This file also contains some 
comments with a more detailed explanation of the code that 
you have to write. 

To run the program, you will need several other modules, all of 
which are stored on the course directory and listed in the 
configuration file. Music. config. You should not need to 
modify any of these other modules. 
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Notes: 
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This chapter discusses how to perform basic filing operations 
such as creating, opening, closing and deleting files. It covers 
only operations on the files themselves, not the content of the 
files. The next two chapters. Streams and NSSegment, discuss 
how to access the content of a file. 



11.1 Naming files 



Before you can operate on a file, you must first have a way to 
identify that file. You can identify a Viewpoint file by 
reference, by attributes, or bypath name. 

The most common way to locate a file is by reference. An 
NSFile.Reference is a unique identifier for a file: it includes the 
name and network location of the file service containing the 
file, and a unique identifier for the file on that volume: 

NSFile.Reference: TYPE a record [ 
filelD: NSFiie.lD, 
service: NSFiie.Service]; 

NSFiie.Service: TYPE = long pointer to NSFiie.ServiceRecord; 

NSFNe.ServiceRecord: TYPE a record [ 
name: NSName.NameRecord, 
systemElement: NSFiie.SystemElement]; 

A service specifies the physical location of a file; that is, the 
machine where the file resides. A f Held is a unique identifier for 
a file on a particular machine. Section 11.3, Opening remote 
files, provides more information on Service. For now, you just 
need to be aware that a Reference uniquely specifies a file. 

The second way to name a file is by attributes. To name a file 
using attributes, you must create an array of attributes that 
contains at least the file's name and version number. (For more 
information on specifying attributes, see Chapter 10, NSFile 
Attributes.) 

The third common way to identify a file is by path name. A 
path name is a hierarchical list of directories in the path to the 
file, such as Working/Current/temp.mesa. The path name may 
be relative to a specified starting directory or to the root file. 

The following sections contain examples of each of these 
methods. 
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11.2 Opening local files 



If you want to be able to do anything useful with a file, such as 
examine its contents, change its attributes, modify its contents, 
or delete it, you first need to open the file. When you open a 
file, the file system gives you a handle to that file. A handle is 
effectively just a pointer to a particular file, although the 
actual structure of a handle is private to the implementation: 

NSFiie.Handle: type ■ [2]; 

Having a handle marks the file as "in use," so that other 
processes are aware that you are using the file, but does not 
necessarily restrict other processes from using the file 
simultaneously. 

When you acquire a file, you can also associate controls with 
your file handle. Controls are essentially ways to describe your 
use of the file. There are three types of controls: locks, 
timeouts, and access. 

A lock is a restriction on the ways that other sessions can use a 
file. For example, you might wish to specify that no other client 
can read or modify the file while you are using it. Note that a 
lock only restricts file access through other sessions, not 
through other handles in the same session; this is not a comlete 
locking mechanism. You can open a file several times within a 
single session, thereby creating several distinct handles. The 
default lock is none, which only prevents other processes from 
deleting the file. 

A timeout control specifies a length of time that you are willing 
to wait to acquire the file before the attempt times out. 
NSFiling defines a defauitTlmeout. 

An access control determines the access that a particular file 
handle allows; this can be read, write, owner, add, remove, or 
some combination of the above. The default is fullAccess, 
which sets all the accesses to true. 

The following sections discuss various ways to open files, but 
do not show examples of using controls, since the defaults are 
sufficient for most uses. For more information on controls, see 
the Filing Programmer's Manual. 



11.2.1 NSFile.Open 



The most general way to open a file is by calling NSFiie.Open: 

NSFile.Open: procedure [ 

attributes: NSFiie.AttributeList, -name file by attributes 
directory: NSFiie.Handle ^ NSFiie.nullHandle, 
controls: NSFiie.Controls [], 
session: NSFlle.Session <^NSFile.nullSession] 
RETURNS [file: NSFiie.Handle]; 

The attributes parameter identifies the file that you wish to 
open; you are thus naming the file by attributes. The directory 
parameter specifies a directory in which to start searching for 
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the file. If you don't know or don't care where the search 
should begin, you can leave this defaulted to the null handle. 
In the example below, the directory is passed in as a parameter. 

controls and session have default values; all the examples in 
this chapter use these default values. See the Filing 
Programmer's Manual if you want more information on either 
of these parameters. 

Here is an example of calling Open: 

OpenFile: PROCEDURE[directory: NSFiie.Handle, 
name: xstring.ReaderBody, 
version: cardinal] 
RETURNS [file: NSFiie.Handle] a 

BEGIN 

nsName: NSString.String <— 

xstrlng.NSStringFromReader [@name, sysZ]; 

specify the attributes used to name the file 
-need at least name and version 

attributes: array [0..2) of NSFiie.Attribute <- [ 

[name[nsName]], 

[version[version]] ]; 

-open the file 

file <-NSFiie.Open[attributes: descriptor [attributes] , 
directory: directory] ; 

-perform operations on the file.. ..then free storage and file 

NSString.FreeStrlng[sysZ, nsName]; 

NSFiie.Close[directory]; 
end; 

This example creates an attributes record that contains the 
name and version, and uses that attributes record to identify 
the file in the call to NSFiie.Open. 

Once the file is open, you can perform operations on it. Before 
exiting the procedure, the final step is to free the storage from 
the system zone and close the file. (Section 4 discusses closing 
files in more detail.) 



11.2.2 NSFile.OpenByReference 



If you have a reference to a file, you can use 
NSFile.OpenByReference instead of NSFiie Open: 

NSFile.OpenByReference: procedure [ 
reference: NSFiie. Reference, 
controls: NSFiie.Controls [], 
session: NSFiie.Session ^NSFiie.nullSession] 
RETURNS [NSFiie.Handle]; 

Open By Reference is less general than Open, but is somewhat 
simpler to use if you already have a reference to the file. 
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11.2.3 OpenByName 



NSFiie.OpenByName is another alternative to Open: 

NSFiie.OpenByName: procedure [ 
directory: NSFiie.Handle, 
path: NSFiie.String, 
controls: NSFiie.Controls <- [1. 
session: NSFiie.Session <-NSFiie.nullSession] 
RETURNS [NSFiie.Handle]; 

OpenByName opens a descendant of a directory with a given 
path name. If directory is null, the path name is assumed to be 
relative to the root file. For example: 

BEGIN 

nsName: NSString.String <--NSString.StringFromMesaString [ 

"Blackjack/temp/BlackJack.df"]; 
file <r- NSFiie.OpenByName [ path: nsName ]; 
NSFiie.Close [directory]; 
NSString.FreeString [nsName]; 
end; 

This fragment will open a file called BlackJack.df on the 
subdirectory temp, on the directory blackjack. Your path name 
can include as many subdirectories as you like; you must 
separate directories with the / character. 



11.2.4 Catalog.Open 



You can also open files with the Catalog interface. A catalog is 
a file that is a direct descendant of the root file, so a catalog is 
just a special case of a directory. The Catalog interface provides 
procedures for creating and opening catalogs and files 
contained in catalogs. 

The two most commonly used catalogs are the system catalog 
and the prototype catalog. The system catalog contains TIP 
files, program beds, font files, and any other files that you 
bring over from XDE. The prototype catalog contains blank 
copies of icons that the user can copy onto his desktop. 

The two relevant open operations are Catalog.Open, and 
Catalog.GetFile. These procedures open a catalog and open a file 
within a catalog, respectively. 

Catalog.Open: PROCEDURE [ 
catalogType: NSFiie.Type, 
session: NSFiie.Sesslon <-NSFiie.nullSession] 
RETURNS [catalog: NSFiie.Handle]; 

Catalog.GetFile: PROCEDURE [ 

catalogType: NSFUe.Type <-BWSFiieTypes.systemFileCatalog, 

name: xstring.Reader, 

readonly: boolean false, 

session: NSFile.Session <-NSFlle.nullSession, 

returns [file: NSFiie.Handle]; 
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You can use these procedures to operate on any catalog: the 
system catalog, the prototype catalog, or any other catalog. If 
you want to use one of the well-known catalogs, you will have 
to get the file type for that catalog from the BWSFIieTypes 
interface. The example below uses the system catalog: 

GetFlieFromCataiog: public procedure [name: xstnng.Reader] 
RETURNS [file: NSFiie. Handle] » 

BEGIN 

catalogType: NSFiie.Type <- BWSFiieTypes.systemFlleCatalog; 
file <-Cataioq.GetFile [cataloqTvpe: cataloqTvpe , 
name: name, 

readonly: true]; - if file not found nullHandle returned 

end; 

This example obtains the file type for the system catalog, and 
then calls GetFlle to search for a file with the given name. If the 
file is in the catalog, GetFile returns a handle to it; if the file is 
not in the catalog, GetFile returns a null handle. Note that with 
Catalog operations, you pass in the file name directly, without 
creating an attributes list. 

If the catalog does not exist, then Catalog will raise a filing 
error. ViewPoint will catch the error and post a message in the 
Attention window. If this isn't how you would like to handle 
this situation, you can explicitly call cataiog.Open to make sure 
that the catalog type is valid and if it is not valid, then handle 
the error yourself. 



11 .3 Opening remote files 



opening a remote file (a file on another machine) is not much 
more complicated than opening a local file. To open a remote 
file, you get a file handle to the machine on which the file 
resides, and then specify that file handle as the directory when 
you ask to open the file. To get a handle to the machine, call 
Open, specifying the service attribute to identify the machine. 
The service attribute is of type Service: 

NSFiie.Service: type = long pointer to ServiceRecord; 

NSFiie.ServiceRecord: type = record [ 
name: NSName.NameRecord, 
systemElement: NSFUe.SystemElement <— 
NSFiie.nullSystemElement]; 

NSName.NameRecord: TYPE = record [ 
org: NSName.Organization, 
domain: NSName. Domain, 
local: NSName.Local]; 

NSFile.SystemElement: type = System.NetworkAddress; 

Thus, to uniquely specify a remote service, you need both the 
name of that service and its network address. (The reason for 
this is that there might be more than one service on a given 
machine.) 
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If you do not specify an address for the system element, the file 
system will look up the name of the service in the 
Clearinghouse to get its networl< address. 

To minimize repetitive lookups, it maintains a cache of service 
records with network addresses. If you want to get such a 
reference from the cache, you can call MakeReference: 

NSFiie.MakeReference: procedure [ 
fllelD: NSFile.lD, 

service: NSFiie.Service <-NSFiie.nullServlce] 
RETURNS [reference: NSFiie.Reference]; 

Section 1 1 .8 has an example of this procedure. 

Here is an example that opens a file on a remote machine: 

hostHandle: NSFiie. Handle <-NSFiie.nullHandle; 

< <host is an XString.ReaderBody obtained from the user to 
specify the machine of choice. If host is not NIL, then get a 
handle to it; otherwise, use the default value (nullHandle), 
which specifies the root directory of the local volume. > > 

IF NOT XString.Empty[@h0St] THEN { 

servlceRec: NSFile.ServiceRecord; 
< < array of attributes for calling Open. This example 
specifies only the service attribute. > > 
attribute: array [0..1) of NSFile. Attribute <- 
[servlce[@serviceRec]]; 

<<get host name into proper format (first convert from 
XString to NSString, and then from NSString to 
NSName)>> 

nsName: NSName.Name <-NSName.NameFromString[ 
z: Heap.systemZone, 
s: xstring.NSStringFromReader 
[@host, Heap.systemZone]]; 

set up the name field of the service record 
-use the default network address 
serviceRec.name ^ nsName t ; 

<<open host machine. Note that with remote operations, 
you need to catch Courier.Error. > > 
hostHandle ^NSFile.Open[DESCRiPTOR[attribute] 

iNSFiie.Error » > continue; 

Courier.Error ss > continue]}; 

The point of this code is to get a handle to the remote machine 
whose name is host. If host is not an empty string, call Open, 
identifying the file by attributes. In this case, we use only one 
attribute to identify the file: the service attribute. The service 
attribute includes only the name of the service; we use the 
default address, which means that the file system will obtain 
the address from the Clearinghouse. 

Once hostHandle has been initialized, you can use it as the 
directory parameter to other NSFiling procedures. 
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11.4 Closing files 



When you are finished with a file, you must close it. Once you 
have closed a file, your handle is no longer valid, and other 
clients may move or delete the file. 

NSFile.ClOSe: PROCEDURE [ 

file: NSFiie.Handle, 

session: NSFiie.Session <-NSFiie.nullSession]; 

If the file handle is invalid, the NSFile implementation will raise 
NSFile.Error. After calling Close, you should set your file handle 
to NIL to ensure that you don't try to use it again. 



11.5 Creating files 



The NSFile and Catalog interfaces also provide procedures to 
create new files. When you create a file, you do not necessarily 
associate any contents with the file; instead, you typically 
associate content with the file later. NSFiling itself does not 
care about the contents of the file; it allocates storage for the 
content, but does not manipulate the content. (See the next 
chapter. Streams, for information on putting content in files. 
For now, we limit the discussion to creating the file itself.) 

You can also create files by other means, such as copying 
existing files. For more information on other methods, see the 
Filing Programmer's Manual. 



11.5.1 NSFile.Create 



The most general way to create a new file or directory is by 
calling NSFile.Create. The file that you create can either be 
temporary or permanent (contained in a directory). 

NSFile.Create: procedure [ 
directory: NSFiie.Handle, 

attributes: NSFiie.AttributeList <-NSFiie.nullAttributeList, 
controls: NSFiie.Controls ^ [], 
session: NSFiie.Session «-NSFiie.nullSession] 
returns [file: NSFiie.Handle]; 

Note that you must first open the directory in which the file is 
to be located. Specifying a null directory will create a 
temporary file. Here is an example of a procedure that creates 
a file and returns a handle to that file. 
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CreateFile: public procedure [ 
catalogType: NSFiie.Type, 
name: xstring.Reader, 

type : NSFiie.Type, type of file being created 
isDirectory: boolean f- false, 
size: long cardinal <- 0] 

RETURNS [file: NSFiie. Handle <-NSFiie.nullHandle] - 

BEGIN 

catalog: NSFiie.Handle <- Catalog. Open [catalogType]; 
nsName: NSString.String 

xstring.NSStringFromReader [name, zone]; 

attributes: array [0..4) of NSFiie.Attribute ^ [ 

[name[nsName]], 

[isDirectory[isDi rectory]], 

[sizelnBytes[size]], 

[type[type]]]; 
IF catalog = NSFiie.nullHandle then return; 
file <- NSFiie.Create [ 

directory: catalog , 

attributes: descriptor [attributes] I NSFiie. Error = > 

{HandleError[error]; continue}]; 
NSFiie.Close [catalog]; 
NSString.FreeString [zone, nsName]; 
end; 

This procedure opens the catalog in which the file is to be 
located, creates an attributes record, and then creates a file in 
the specified directory with the specified attributes. 

One thing you should notice from this example is the 
sizelnBytes attribute. This attribute is optional, but is very 
important; it specifies the size of the initial chunk of storage 
for the file. If you do not include this attribute, the file will 
grow as it is written; this can scatter the file's pages over the 
disk, and can result in very long access times. Thus, you should 
always make a good guess as to the final size of your file and 
include that value in your attributes. 

Trying to create a file that already exists will generate an error. 
If this happens, you should catch the signal and create a new 
file with a higher version number. (Section 1 1.9 provides more 
information on NSFiie errors.) 



11.5.2 Catalog.Create 



The Catalog interface provides an easy way for you to create a 
file that is a descendant of a particular catalog: 

cataiog.CreateFile: procedure [ 

catalogType: NSFile.Type>- BWSFileTypes.systemFileCatalog, 

name: xstring.Reader, 

type: NSFiie.Type, 

isDirectory: boolean false, 

size: long cardinal <- 0, 

session: NSFile. Session «-NSFiie.nullSession, 

returns [file: NSFiie.Handle]; 

Note that with CreateFile, you just pass name, type, isDirectory 
and size as parameters; you don't specify file attributes in an 
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AttributeList. You are limited to the attributes listed in the 
procedure declaration, however. (If you want additional 
attributes, you will have to set them later, after you have 
created the file.) As you can see from the type declaration, if 
you don't specify a catalog, the default is to use the system 
catalog. Once again, you should include the size parameter to 
avoid fragmentation. 



11.6 Deleting files 



NSFIIe.Delete deletes an existing file, removes any association 
with a directory, and frees the resources allocated to the file. If 
the deleted file is a directory, then all descendants are deleted 
too. 

NSFIIe.Delete [ 

file: NSFiie.Handle, 

session :NSFiie.Session ^ NSFiie.nullSession]; 

To correctly delete a file, there can be no other handles 
attached to the file. If an error occurs during the Delete 
process, the file handle will remain valid; otherwise, the handle 
becomes invalid. 



11.7 Finding files 



Suppose you want to locate all files whose name contains a 
particular string or all files created by a particular person. In 
such cases, you can use NSFile.Find: 

NSFiie.Flnd: procedure [ 
directory: NSFile.Handle, 
scope: NSFiie.Scope [], 
controls: NSFiie.Controls [], 
session: NSFiie.Session NSFiie.nullSession] 
RETURNS [file: NSFiie.Handie]; 

scope is the most important parameter here; scope is how you 
specify the subset of files that you are interested in: 

NSFiie.Scope: TYPE a RECORD [ 

count: CARDINAL ^last[cardinal], 
direction: NSFiie.Direction <- forward, 
filter: NSFiie. Filter «-NSFiie.nullFilter, 
ordering: NSFile.Ordering 4-NSFiie.nullOrdering, 
depth: cardinal <- 11; 

count, direction, ordering, and depth are relatively 
straightforward; filter is the hard part. 

count is the maximum number of files that you are interested 
in. The file system will continue to search until it has found a 
match, until it has searched count files, or until it has run out of 
files to search. The default value considers all possible files. 

direction is the direction of the search: you can either start at 
the end of the directory and work back to the beginning, or 
vice versa. 



VIEWPOINT programming COURSE 



11-9 



NSFILNG 



ordering is the order in which you want to search the directory. 
nullOrdering defaults to the directory's ordering attribute. 
(Directories can have complicated orderings; see section 6.3.6 
of the Filing Programmer's Manual for details.) Your other 
choice for ordering is defaultOrdering; no other ordering 
schemes are implemented. defaultOrdering specifies 
alphabetical order by file name. 

depth is the number of levels subdirectories) in the file system 
hierarchy that you want the search to encompass. 

filter is the real basis of the scope. In most cases, the filter is the 
only part of the scope that changes. The filter may be an 
arbitrarily complex relational expression, as described in the 
next section. 



11.7.1 Filters 



NSFile. Filters allow you to construct a relational expression 
made up of attributes and the relations "and," "or," and 
"not". Here is the declaration of Filter: 

NSFiie.Filter: TYPE ■ machine dependent record [ 
var: select type: FilterType from 
less, lessOrEqual, equal, notEqual, greaterOrEqual, greater 
a > [attribute: NSFiie.Attribute, 

interpretation: NSFiie.lnterpretation <r- none], 
matches ■ > [attribute: NSFiie.Attribute], 
and, or a > [list: long DESCRiPTOR for array of NSFiie.Filter], 
not ■ > [filter: long pointer to NSFiie.Filter], 
none, all ■ > [], 
endcase]; 

You can create various combinations of these filters, 
depending on the search criteria that you are interested in. For 
example, if you wanted to find a file whose name was 
"Training Notes," with a version number less than 3, that was 
not created by anyone with a first name of "Jim," then you 
would make the following filter: 

[and[ 

[equal [[name ["Training Notes"]]]], 
[less [[version [3]]]], 

[not[ [matches[[createdBy ["Jim *"]]]] ]] 

]] 

The Mesa code for this filter would look something like this: 

createdByFilter: NSFiie.Filter 
[matches [[createdBy ["Jim 
*"]]]]; 

f ilterArray: array [0..3) of NSFiie.Filter <- [ 
[equal [[name ["Training Notes"]]]], 
[less [[version [3]]]], 
[not [©createdByFilter]] ]; 

filter: NSFiie.Filter <- [and[DESCRiPTOR[filterArray]]]; 
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This filter will search for files whose name attribute is "training 
notes," whose version attribute is less than 3, and whose 
createdBy attribute does not pass createdByFllter. 

Notice that the not operation requires a long pointer to a 
Filter, so you need to first create the "inner" filter, and then 
put a pointer to it in the "outer" filter. 

You can also use the two wildcards * and # in your matches 
expression. The * character matches zero or more characters 
within a string attribute; # matches any single character. 



11.7.2 NSFile.Find 



Once you specify a scope, you can call Find to locate and open a 
file in a particular directory. Here is an example that finds any 
file whose name matches a specified string: 

FindFlle: procedure [file: xstrmg.Reader, 
zone: uncounted zone, dir: NSFiie.Handle] 
RETURNS [handle: NSFiie.Handle ^NSFiie.nullHandle] = 

BEGIN 

nsSource: NSString.String ^xstring.NSStringFromReader[ 
file, zone]; 

- if no directory is specified use the root file 
IF dir m NSFiie.nullHandle THEN dir <- 
NSFiie.OpenByReference[reference: NSFiie.nullReference]; 

handle <-NSFiie.Find[ 
directory: dir, 

scope: [filter: [matches[[name[nsSource]]]l]! NSFiie.Error = > 

CONTINUE]; 

NSString.FreeString[Defs.zone, nsSource]; 
end; 

This example opens the specified directory. If there is no 
directory, then it uses the root directory. Next, it searches the 
open directory for all files whose name attribute matches the 
file parameter. 



11.8 Listing files 



You can use NSFiie.List to enumerate files in a directory and 
return the desired attributes of each listed file: 

NSFiie.List: PROCEDURE [ 

directory: NSFiie.Handle, 

proc: NSFiie.AttributesProc, 

selections: NSFiie.Selections, 

scope: NSFiie.Scope «- [], 

clientData: long pointers- nil, 

session: NSFile.Session ^ NSFile.nullSession]; 

NSFiie-AttributesProc: TYPE a procedure [ 

attributes: NSFiie.Attributes, clientData: long pointer] 
RETURNS [continue: boolean <-true]; 
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directory is the directory tliat you want to search, proc is a call 
back procedure that you want the file system to call when it 
finds an appropriate file. For each file that matches the 
specified scope, the file system will call proc with attributes, 
which is a pointer to an attributes record. 

clientOata is a long pointer to information of your choice. If 
there is any additional information that you want available 
when proc is called, you can pass it in via clientData. 

Here is an example of using List: 

< < The file system will call Enumerate when it finds a file that 
matches the search criteria. When called. Enumerate will open 
the file by reference. If there are problems, abort this 
enumeration and continue the search with other files. 
Enumerate: NSFiie.AttributesProc = { 

ref: NSFiie.Reference ^NSFiie.MakeReference[ 

filelD: attrlbutes.filelD! NSFiie.Error = > goto Exit]; 
handle: NSFiie.Handle <- 

NSFiie.OpenByReference[ref! NSFiie.Error = > goto Exit]; 

-- do something interesting with file handle 
NSFiie.Close[handle! NSFiie.Error & > continue]; 
EXITS Exit a > null; 

}; 

-This is the procedure that does the actual search. 

ListOirectories: procedure[ 

handle: NSFiie.Handle, file: xstring.Reader] a { 
nsSource: NSString.String <-xstring.NSStringFromReader[ 
file, Defs.zone]; 

-interested in all files whose name matches nsSource 
scope: NSFiie.Scope <- 

[filter: [matches[[name[nsSource]]]],direction:backward]; 
-- get the ID of the file being enumerated 
selections: NSFiie.Selections; 
selections. interpreted[filelD] <-true; 

- if no directory specified use the root 

IF handle a NSFiie.nullHandle then handle <- 

NSFiie.OpenByReference[reference: NSFiie.nullReference]; 

-- call List. This will result in a call to Enumerate for each file 
-that matches the specified scope 

NSFile.List[ 

directory: handle, 

proc: Enumerate , 

selections: selections, 

scope: scopeiNSFiie.Error = > continue]; 

~ free all allocated data and close the directory 
NSString.FreeString[Defs.zone, nsSource]; 
NSFile.Close[handle! NSFiie.Error a > continue]; 

}; 

The parameters to ListOirectories are a handle to a directory, 
and the name of a file. ListOirectories sets up a filter to match 
all files whose name matches the file parameter, and then calls 
NSFiie.List. List calls Enumerate for each file that matches the 
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specified scope; Enumerate can tlien perform any desired 




operations on those files. 


11,9 Errors 




When working with the NSFiling system, you need to concern 




yourself with the errors NSFile.Error and courier.Error. NSFile.Error 




has a parameter that indicates the type of error: 




NSFile.Error: error [error: NSFile.ErrorRecord]; 



NSFiie.ErrorRecord: TYPE b record [ 
SELECT errorType: NSFiie.ErrorType from 
access = > [problem: NSFiie.AccessProblem], 
attributeType,attributeValue ■ > [ 

problem: NSFile.ArgumentProblem, 

type: NSFiie.AttrlbuteType, 

extendedType: NSFiie.ExtendedAttributeType <- 
LAST[NSFile.ExtendedAttributeType]; 
authentication a > [ 

problem : NSFiie.AuthenticationProblem], 
clearingHouse s > [problem: NSFiie.ClearinghouseProbiem], 
connection = > [problem: NSFiie.ConnectionProblem] ; 
controlType, control Value = > [ 

problem: NSFile.ArgumentProblem, 

type: NSFiie.ControlType], 
handle ■ > [handle: NSFiie.HandleProblem], 
insertion ■ > [problem: NSFiie.lnsertionProblem], 
range ■ > [problem: NSFiieArgumentProblem], 
scopeType, scope Value ■ > [ 

problem: NSFile.ArgumentProblem, 

type: NSFiie.ScopeType], 
service ■ > [problem: NSFiie.ServiceProblem], 
session s > [problem: NSFiie.SessionProblemj. 
space ■ > [problem NSFiie.SpaceProblem], 
transfer ■ > [problem: NSFiie.TransferProblem], 
undefined s > [problem: NSFiie.UndefinedProblem], 
endcase]; 

Within an Error, there are various classes of errors. The error 
classes are Access errors. Argument errors, Authentication 
errors. Clearinghouse errors. Connection errors. Handle errors. 
Insertion errors, Service errors, Range errors. Session errors. 
Space errors. Transfer errors, and Undefined errors. 

Within each of these classes, there are a number of specific 
errors. For example, in the case of an access error, there is a 
parameter problem that indicates the exact nature of the 
problem. This problem is of type AccessProblem: 

NSFiie-AccessProblem: TYPE ■ machine dependent { 

accessRightslnsufficient(O), accessRightslndeterminate(l), 
f ileChanged(2), f iieDamaged(3), f ilelnUse(4), 
f ileNotFound(5), f ileOpen(6), f ileNotLocal(7)}; 

Each of the other classes of errors has a similar list of specific 
errors; consult the Filing Programmer's Manual for a complete 
list. When working with filing operations, you need to catch 
NSfile.Error, select the error class and then select the actual error 
from within the class. For example: 
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NSFileCatchError: procedure [error: NSFiie.ErrorRecord] = 

BEGIN 

WITH mvError: error select from 

access ■ > select mvError.problem from 
fileChanged ■ > << File changed error> > 
fiielnUse = > << File in use error > > 
fileNotFound ■ > << File not found error> > 
endcase; 
handle ■ > 

select myError.problem from 

invalid = > << Invalid handle error> > 
obsolete ■ > << Obsolete handle error > > 
endcase; 

endcase ■ > < < Undefined error> > 
end; 

If you are working with remote files, you also need to be 
concerned with Courier.Error. Like NSfile.Error, this error has a 
parameter that indicates the exact nature of the problem: 

Courier.Error: ERROR [errorCode: Courler.ErrorCode]; 

Courier. ErrorCode: type = { 

transmissionMediumHardwareProblem, 
transmissionMediumUnavailable, 
transmissionMediumNotReady, noAnswerOrBusy, 
noRouteToSystemElement,transportTimeout, 
remoteSystemElementNotResponding, 
noCourierAtRemoteSite, tooManyConnections, 
invalidMessage, noSuchProcedureNumber, 
returnTimedOut, callerAborted, 
unknownErrorlnRemoteProcedure, streamNotYours, 
truncatedTrandfer, parameterlnconsistency, 
invalidArguments, noSuchProgramNumber, 
protocolMlsmatch, duplicateProgramExport, 
noSuchProgramExport, InvalidHandle, noError]; 

For more information on any of these error codes, see Section 
6.6.4. 1 of the Pilot Programmer's Manual. 



11.10 Summary 



To open a file so that you can read or write to it, you generally 
use NSFiie.Open. Alternatives to Open are 
NSFiie.OpenByReference, NSFiie.OpenByName, and Cataiog.Open. 

To close a file, use NSFiie.Close. 

To create a file, use NSFiie.Create. If you want to create a file in a 
catalog, you can use Cataiog.Create instead. 

To delete a file, call NSFiie.Delete. 

To find or list files matching particular criteria, call NSFile.Find or 
NSFile.Llst. 

There is a complete filing example at the end of Chapter 13, 
NSSegments. This example illustrates a full range of filing 
operations, covering the information in Chapters 10 through 
13. 
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11.11 Exercise 



The exercise for this chapter builds on the exercise for the 
previous chapter. You don't need to have done the earlier 
exercise to do this one, but you do need to have read the 
description of the user interface. If you didn't do the last 
exercise, you should go back now and read the description of 
how the tool operates. 

For this exercise, you need to implement the two procedures 
GetSeiectedFlie and OpenTypedfile. 

GetSelectedFile should open the currently selected file and 
return an NSFiie.Handle to it. If there are any problems, you 
should print an error message to the user and raise the signal 
FileProblem. 

The second procedure, OpenlypedFiie, is more complicated. In 
this procedure, you recieve the name of a file and an operation 
(saveData, loadData, or savelP) as parameters. You need to do 
the following: 

• Check to see if the file is on the desktop or in the system 
catalog. If it is, then just return a handle to it. (See the 
StarDesktop interface for more information on 
manipulating the desktop.) 

• If the file isn't in either the system catalog or on the desktop, 
you need to decide whether to create it or return an error. If 
the operation is loadData, then you are trying to read the 
contents of the file. Since the file doesn't exist, you should 
print an error message and raise the signal FileProblem. 

If the operation is not loadData, then you need to create a 
new file on the desktop. To create the file, you need to 
determine the file type by checking the operation argument 
again. If operation is saveData, then use the type 
SimpleDocumentType; otherwise use IPMasterType. The 
reason for having two file types is that this procedure is 
called to create files both for storing data and creating 
Interpress masters. 

The procedures that you need to modify are in 
MusicFilelmplExerciseB.mesa. This is the same module that you 
worked with in the last exercise. This time, however, we 
provide the attributes code, and you must write the code that 
manipulates the files. The comments in this module describe 
exactly what you need to do. 
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The last chapter discussed how to create, open, close, and 
delete files, but did not discuss how to access the actual 
contents of the file. The two most common ways for a program 
to access the contents of a file are attaching a stream to the 
file, and mapping the contents of the file to virtual memory. 
This chapter focusses on how to attach a stream to a file; the 
next chapter discusses mapping the file to virtual memory. 



12.1 Overview 



A stream is an abstraction for accessing data sequentially: one 
byte at a time, one word at a time, and so on. Streams are 
device-independer)t: you can use streams to access data on 
various different devices, such as local disk files, floppies and 
tape drives. For the purposes of this chapter, however, a 
stream is a connection from a program to a local disk file. If you 
want to know how to use streams to access other kinds of 
devices, see the Pilot Programmer's Manual. 

To use a stream to access the contents of a file, you need to set 
up a connection between your program and the file. Creating 
the stream is device-dependent; you need to use a procedure 
that knows the details of file I/O. The ViewPoint NSFlieStream 
interface provides this procedure. 

Once the stream is established, however, you can use 
procedures from the Pilot Stream interface to do I/O. These 
procedures are device-independent; you use the same I/O 
procedures regardless of the type of the device to which the 
stream is attached. Figure 12.1 illustrates this idea. 
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12.1 A stream to a file 



The rest of this chapter describes how to set access the contents 
of a file using the facilities of NSFileStream and Stream. 
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12.2 Creating a stream 



To open a stream to a file, the first step is to call 
NSFileStream.Create : 

NSFileStream.Create: PROCEDURE [ 
file: NSFiie.Handle, 
closeOnDelete: boolean <- true, 

options: stream.lnputOptions ^stream.defaultlnputOptions, 

session: NSPiie.Session] 

returns [fileStream: NSFiieStream. Handle]; 

file is a handle to the file to which you want to attach the 
stream; you can get the file handle with any of the methods 
described in the previous chapter. Note that file must be a 
handle to a local file; you cannot use NSFiieStream to access 
remote files. 

closeOnDelete specifies whether the file is to be automatically 
closed when the stream is deleted, options controls various 
aspects of the stream, session is as described in Chapter 10, 
NSFiling Operations. 

Create creates a stream to the specified file and returns a 
handle to that stream. The handle is of type NSFiieStream. Handle, 
which is equivalent to a stream. Handle: 

NSFiieStream. Handle: type s record [stream. Handle]; 

stream. Handle: type a LONG POINTER TO stream. Object; 
Stream.Object: TYPE ■ RECORD [ 

options: stream.lnputOptions, 
getByte: stream.GetByteProcedure, 
putByte: stream.PutByteProcedure, 
...]; 

A Stream.Object defines the mechanisms for data transfer to 
and from the particular device for which the stream was 
created. The Object contains specific procedures to do I/O; the 
Stream implementation will call these procedures when the 
client requests a read or write. (The next section covers stream 
I/O in detail.) You don't need to know anything about the 
Object however; the stream handle is all you need. 



12.3 Stream I/O 



Once you have created a stream to a file, you can use the 
facilities of the Stream interface to read and write to the file. 
Note that controls acquired when creating the file handle 
apply when you access the file via the file stream, and are used 
to determine your access to the file. 

The basic output operations for streams are PutByte, PutWord, 
and PutBlock. (PutBlock is discussed in the next section.) The 
procedures are declared as follows: 

stream. PutByte: PROCEDURE [sH: stream. Handle, 
byte: stream. Byte]; 
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Stream.PutWord: PROCEDURE [sH: Stream. Handle, 
word: Stream.Word]; 

These procedures are straightforward; you provide a stream 
handle and a piece of data, and the procedure puts that data 
to the appropriate stream. 

The basic input procedures are GetByte, GetWord, and 
GetBlock. (GetBlock is discussed in the next section.) 

stream. GetByte: PROCEDURE [sH: stream. Handle] 
RETURNS [byte: stream. Byte]; 

stream. GetWord: PROCEDURE [sH: stream. Handle] 
RETURNS [word: Stream.Word]; 

These procedures return the next byte or word (respectively) 
from the specified stream. 

When it reaches the end of an input file, the Stream interface 
raises the signal EndOfStream. You need to catch this signal 
and react accordingly. For example: 

ch: stream. Byte; 

DO - copy the file input to ttie file output 

ch stream.GetByte[input!stream.EndOf Stream = > exit]; 
Stream.PutByte[output,ch]; 

ENDLOOP; 

This example gets a byte from input and puts it to output until 
it reaches the end of the input file. At that point, the Stream 
interface raises the EndOfStream signal, which is caught inside 
the loop. The catch phrase exits the loop, and control will 
resume at the statement following the loop. 



12.3.1 Example of I/O 



Here is an example of a procedure that creates streams on two 
files and then copies the contents of one file to the other. After 
the copy is complete, the streams are deleted, thus closing the 
files. (Deleting a stream automatically closes the file to which 
the stream is attached, unless you change the value of the 
closeOnDelete boolean parameter of NSFiieStream.Create.) 

Copy: PROCEDURE [from, to: NSFile.Handle] s { 
-set up the streams with NSFIIeStream 
input: NSFIIeStream. Handle <- NSFiieStream.Create [f lie: from]; 
output: NSFIIeStream. Handle NSFiieStream.Create [f lie: to]; 

- after Streams are created you can use Pilot Stream operations 
ch: stream. Byte; 
DO ~ copy the file 

ch <- stream. GetByte[lnput!stream. EndOfStream = > exit]; 

Stream.PutByte[output,ch]; 

ENDLOOP; 

Stream. Delete[input]; -deletes stream and closes file 
Stream. Delete[output] }; 
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12.3.2 Block I/O 



Stream blocks allow you to transfer arbitrary data structures, 
stream. Block: TYPE ■ Environment.Block; 
Environment.Block: TYPE ■ RECORD [ 

blockPointer: long pointer to packed array [0..0) 

OF Environment. Byte, 
startlndex, stoplndexPlusOne: cardinal]; 

Stream.GetBlock: PROCEDURE [sH: stream. Handle, 
block: stream. Block] 
returns [bytesTransferred: cardinal, 

why: stream.CompletionCode, 

sst: stream.SubSequenceTypej; 

Stream.PutBlock: PROCEDURE [sH: stream. Handle, 
block: stream. Block, 
endRecord: boolean <- false]; 

Stream.CompletionCode: type = {normal, endRecord, 
sstChange, endOfStream, attention, timeout}; 

To use GetBlock, you must first declare a Block, which includes 
a pointer to a buffer (array) of bytes, and information on 
where to start and stop in the array of bytes. You then call 
GetBlock, passing in a stream handle and your Block. GetBlock 
will retrieve bytes from the file and store them into the buffer 
specified by block, as illustrated in Figure 12.2. 





block 




blockPointer startlndex stof: 


>lndexPlusOne 




^ Buffer of uninterpreted bytes buffer 











1 2.2 After a GetBlock operation 
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Once you have the array of bytes, you can use Mesa's loophole 
operation to operate on the bytes as if they were a data 
structure. The loophole operation allows you to circumvent 
Mesa's type checking; you can use loophole to treat any type as 
if it were another, as long as the two types occupy the same 
number of words. Thus, you can loophole the block pointer 
into a pointer to another record structure, as illustrated in 
Figure 12.3. 



block 



blockPointer 



startlndex 



stoplndexPlusOne 



buffer 



1 



LOOPHOLE 



block 



blockPointer 



startlndex 



StoplndexPlusOne 



buffer 



name 


ssn 


employeeNumber 


gradeLevel 



myRec 



12.3 Using stream block operations 
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Here is a code fragment that corresponds to the above figure: 

Employeelnfo: TYPE ■ machine dependent record[ 
name(O): packed array[0.. 30) of character, 
ssn(15): long cardinal, 
employeeNumber(17): long cardinal, 
gradeLevel(19): cardinal]; 

-size of record in bytes 

RecordSize ■ size [Employeelnfo] * Environment.BytesPerWord; 
inputStream,outputStream: stream. Handle «- nil; 

myRec: long pointer to Employeelnfo; 

"declare a buffer that has same number of bytes as the record 

buffer: packed array[0.. RecordSize) OFEnvironment.Byte; 

-create a stream block with pointer to your buffer 

block: stream. Block <- [©buffer, 0, RecordSize]; 

-need to initialize stream handles here by calling 
-NSFileStream. Crea te 



completionCode: stream.CompletionCode normal; 
UNTIL completionCode = endOfStream do 
-get a block 

[block.stoplndexPlusOne, completionCode,] 
stream. GetBlock[inputStream,block]; 
- lay template on data 

myRec <-LOOPHOLE[block.blockPointer]; 
-modify record 

myRec.gradeLevel myRec.gradeLevel + 1; 
-put modified record to output file 

stream.PutBlock[sH: outputStream, block: block, 

endRecord: true]; - ensure block is sent before return 

ENDLOOP; 

In this example, we declare a buffer, make a stream. Block that 
has a pointer to that buffer, and then call GetBlock, passing in 
our input stream and the block. GetBlock fills the buffer with 
bytes taken from the stream. We then use loophole to access 
the block pointer as if it were a pointer to our record structure. 
We can then use the record pointer to modify the bytes as if 
they were a record of type Employeelnfo. (Note that we never 
actually declare a record of type Employeelnfo; instead, we use 
the buffer of bytes as if it were the record.) When we have 
finished modifying the record, we use PutBlock to write the 
buffer to another stream. 

You should notice that GetBlock normally uses the completion 
code endOf Stream instead of signalling endOf Stream. To 
cause GetBlock to raise the signal, you can call 
stream. SetlnputOptions to set signalEndOfStream in 
inputOptions to true. (Recall from section 11.2 that 
NSFileStream.Create has an options parameter that specifies 
certain characteristics of the stream. stream.SetlnputOptions is a 
procedure that allows you to change the characteristics of a 
stream once it has been created.) 
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12.3.3 Random access 



Although streams are generally used for sequential access, 
NSFileStream supports random access to the contents of local 
files. Note, however, that you should not do a lot of random 
access with streams. If you need to do a lot of random access, 
you should use mapping instead of streams. (The next chapter 
discusses this method.) 

To get to a particular position you call Stream.SetPosition. 
Similarly, you can determine the current location within a file 
by using Stream.GetPosltion: 

Stream.POSition: TYPE = LONG CARDINAL; 

Stream.GetPosltion: PROCEDURE [SH: stream. Handle] RETURNS 

[position: stream.Position]; 

Stream.SetPosition: PROCEDURE [sH: stream. Handle, 
position: stream.Position]; 

In both of the procedure declarations, the position parameter 
is the byte-index of the next data in the stream to be read or 
written, where the first byte in the file has the index 0. Here is 
some code to illustrate the use of these procedures: 

Advance: PROCEDURE[stream: stream. Handle, 
advanceAmount: Stream.Position] 
RETURNS [newPos: Stream.Position] ■ 

BEGIN 

position: stream.Position "^stream.GetPosition fsH: stream]; 
newPos <~ position + advanceAmount; 
Stream.SetPosition [sH: stream, position: newPos]; 
end; 



12.3.4 Miscellaneous operations 



NSFileStream also provides procedures that allow you to 
obtain a count of the data bytes in a file stream, or set the 
length of data bytes in the file stream: 

NSFiieStream.GetLength: procedure [ 
fileStream: NSFileStream. Handle] 
RETURNS [lengthlnBytes: long cardinal]; 

NSFileStream.SetLength: PROCEDURE [ 
fileStream: NSFiieStream.Handle, 
lengthlnBytes: long cardinal]; 

Note that the length returned by GetLength is not necessarily 
equal to the size of the underlying file. For example, if you are 
appending data to the stream, the actual size of the file may be 
smaller than the number of bytes in the stream. See the Filing 
Programmer's Manual for details. 

Note also that you can use SetLength to make the length of the 
file stream either larger or smaller. 



VIEWPOINT programming COURSE 



12-7 



STREAMS 



Another ^4SFileStream procedure that you might find useful is 
FileFromStream: 

NSFiieStream.FlleFromStream: procedure [ 

fileStream: NSFiieStream. Handle] 
RETURNS [file: NSFiie.Handle]; 

This procedure returns a copy of the file handle to which the 
stream is attached. It is a copy of the handle used to acquire the 
stream; it is valid only during the session during which you 
acquired the stream. 



12.4 Deleting streams 



Since a stream is a connection between a program and a 
device, the program should never terminate without telling 
the device that the connection is no longer open. For every 
stream you create, you must call stream. Delete to close the 
stream when you are finished with it. 

stream. Delete: PROCEDURE [sH:stream. Handle]; 

After closing the stream, you should always set the stream 
handle variable to nil, to ensure that you don't accidentally try 
to use it later on. (Delete invalidates the stream handle, but 
does not set it to nil.) 



12.5 Summary 



Streams provide sequential access to data. You can use streams 
to access various devices, but this chapter only discussed how to 
use them to access the contents of local disk files. 

To create a stream, you need to use a procedure that knows 
something about the device to which you are attaching a 
stream. To attach a stream to a local disk file, you use 
NSFileStream.Create. 

Once you have created a stream, you perform I/O with the 
Stream procedures PutByte, PutWord, PutBlock, GetByte, 
GetWord, and GetBlock. 

To do random access, use stream.GetPosition and 
stream.SetPosition. 

When you are through, call stream. Delete to delete the stream. 



12.6 Exercises 



The tool for this chapter is the Stream Tool, which allows you to 
load a file (simple document) into the tool window, or load the 
contents of the wi ndow i hto a f i le. 

To load a file into the tool, select the file and invoke Load. To 
store the current contents of the window into a file, select the 
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destination file and invoke Save. You can use standard editing 
techniques to change the contents of the window. 

You must write the commands Load and Save. The procedures 
that you need to change are in the module 
StreamToollmplTemp.mesa. You will also need the following 
modules: 

StreamToolDefs 
StreamToollmpI 
StreamToollmplTemp 
Strea m Too I M sg I m pi 
StreamTool.config 
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Notes: 
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The last chapter discussed how to access the contents of a file 
with a stream; this chapter discusses how to access the contents 
of a file by mapping the file to virtual memory. 

Streams are an easy way to access a file sequentially. For some 
applications, however, you want to access a file via a data 
structure rather than sequentially. For example, if you have a 
file that contains a binary tree of data, you probably need to 
access that data as a tree and not as a sequence of bytes. For 
this kind of application, you should modify the file by mapping 
it to virtual memory rather than using a stream. 

This chapter describes how to use the facilities of the Services 
NSSegment interface and the underlying Pilot Space interface 
to map files to virtual memory. You should be familiar with the 
basic idea of virtual memory before you read this chapter. 



1 3.1 Definition of terms 



Page: One page is Environment. wordsPerPage (256) words or 
EnvironmentbytesPerPage (512) bytes. 



13.2 Virtual memory overview 



Since no machine ever has enough real memory, virtual 
memory has become the standard way to combine the 
resources of the disk drive with the resources of real memory. 
The idea is to create the illusion of an environment that has the 
size of the disk and the speed of main memory. 

The underlying premise is that you don't have to have all of a 
program in real memory to execute the program. Rather, the 
parts of the program that are currently executing are in real 
memory, and the rest of it is "in virtual memory." Everything 
that is "in" virtual memory must be backed by a page on the 
disk; the disk is the real location of the information. 

Since there are more pages in virtual memory than can fit in 
real memory, there will come a point when a program tries to 
access a page that is not currently in real memory. At this point, 
the operating system will swap out pages that are no longer 
needed and swap in the necessary page and any other pages of 
the containing swap unit. (A swap unit is just a way to group 
pages so that they will be swapped in and out together.) 

The operating system handles all swapping; you never know 
whether your code is in real memory or not. However, 
swapping pages in and out takes more time than just loading a 
program into real memory and executing it. Virtual memory 
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allows you to execute more programs, but each individual 




program may be somewhat slowed by swapping. 


13.3 Mapping 



Every piece of virtual memory that contains useful information 
must have a backing file on the disk. Typically the backing file 
for a piece of virtual memory is anonymous, but it is possible to 
set up a mapping between a specific file and a specific piece of 
virtual memory. Thus, you can get a pointer to a piece of virtual 
memory that is backed by your file, modify the virtual memory, 
and then write the information back out to the file on the disk. 

The simplest view of the relationship between an interval of 
virtual memory and its backing store is that the virtual memory 
and the file always contain the same data. This isn't really the 
way it works, however, since changes to the virtual memory 
interval aren't immediatly reflected in the backing file. 

A page that has been changed in memory but not in the 
backing file is "dirty." The operating system writes dirty pages 
to the backing file before it swaps the page out of virtual 
memory, but you should not count on this for backup since you 
have no way of knowing when or if it will happen. Instead, you 
can explicitly write dirty pages to the disk with procedure calls, 
either in the middle of modifications (as an intermediate 
backup) or when you are through making changes. 

The rest of this chapter describes how to map a file to virtual 
memory, how to modify it, and how to write the modified 
contents of virtual memory back to the file. 



1 3.3.1 Setting up the mapping 



To map a file to virtual memory, you call NSSegment.Map: 

NSSegment.Map: PROCEDURE [ 
origin: NSSegment.Origin, 
access: NSFiie.Access <-NSFiie.ReadAccess, 
usage: Space.Usage <— space. unknownllsage, 
life: space.Life alive, -ordead 
swapUnits: Space.SwapUnitOption «- 

space.defaultSwapUnitOption, 
session: NSSegment.Sesslon <-NSSegment.nullSession] 
RETURNS [mapUnit: space.lnterval]; 

NSSegment.Origin: TYPE = RECORD [ 

file: NSFiie.Handle, 
base: NSSegment.PageNumber, 
count: NSSegment.PageCount, 
segment: ID «-NSSegment.defaultlD]; 

space.lnterval: TYPE ■ RECORD [ 
pointer: long pointer, 
count: Environment.PageCount]; 
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As illustrated in Figure 13.1, Map takes a specified portion of a 
file, copies it to virtual memory, and returns a pointer to the 
appropriate pages in virtual memory. (The next section 
provides detail on the space.lnterval that Map returns.) 




Figure 13.1 Mapping a file to virtual memory 



The origin record specifies the location of the information that 
you want to map. Within an origin, file specifies the file of 
interest, base is the page in that file where you want to start 
processing, and count is the number of pages of interest. 

The segment field allows you to specify the portion of a file 
that you are interested in. Every file is composed of segments. 
There must be at least one segment, the default segment, in a 
file. Although the NSSegment interface currently supports 
multi-segment files, their use is not recommended. Thus, you 
should always leave the segment field defaulted. Figure 13.2 
illustrates an origin record. 



Origin specifies pages, (starting from base for count pages), 
of segment number segment in file file. 



origin 



file 


base 


count 


: segment .' 


myFile 


1 


2 


: N/A : 



origin specifies a two-page chunk 



myFile 




Figure 13.2 An NSSegment.Origin 




The access parameter to Map determines whether you are 
allowed to write in the mapped space after you map a file. You 
must have at least read access, or you will raise NSFiie.Error. 
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Note that the default access is read (even if you have write 
access to the file), so you will have to change this if you wish to 
write the file. 

usage provides a hint as to how the space will be used. This 
data will be made available to tools like the debugger and the 
performance management package. The Space interface 
defines an interval of usages that is further managed by the 
SpaceUsage interface. See the Pilot Programmer's Manual for 
details. 

life specifies whether or not the initial contents of the backing 
file are useful, alive specifies that a swap unit initially contains 
useful data; dead specifies that it does not. See the Pilot 
Programmer's Manual for more details. 

The swapUnit parameter specifies the size of the swap units 
that Pilot should use when your program takes a page fault. If 
you don't specify a size, it will be defaulted. See the Pilot 
Programmer's Manual for details of default swap units. 

session is as described in Chapter 1 0, NSFile Attributes. 

Here is an example of calling Map: 

-- set up to retrieve attributes. 

selections: NSFiie.Selections; 

attri butes : NSFile. Attri butesRecord ; 

-open the file 

file: NSFile. Handle <-NSFiie.OpenByReference[fileReference]; 

-retrieve the sizelnPages attribute 
selections. interpreted[sizelnPages] <-true; 
NSFiie.GetAttributes[file, selections, attributes]; 

~ map file to VM so we can write to it. Specify entire file as 
-origin; allow write access. 
space: Space.lnterval <-NSSegment.Map[ 

origin: [flle:file, base: 0, count: attributes.sizelnPages], 

access: NSFiie.full Access]; 

This example maps an entire file. The first step is to retrieve the 
sizelnPages attribute to find out how big the file is. The second 
step is to map the file, using the sizelnPages information to 
specify that we are mapping the entire file. 



1 3.3.2 Accessing the file 



Map returns a space.lnterval, which describes a sequence of 
pages in the virtual memory. An Interval contains a pointer to 
the first page and a count of the number of pages: 

Space.lnterval: TYPE a record[ 

pointer: long pointer, count: Environment. PageCount]; 

Since you have a pointer to the starting address of the interval, 
you can impose any structure on your interval of virtual 
memory by creating a variable that is a pointer to a data object 
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and then assigning to tliat pointer the address of the segment. 
(This typically involves a loophole operation.) For example: 

"declare a record type with a long pointer and two bools 
RecType: TYPE ■ record [ 

someString: xstring. Reader, 

isEnglish: boolean, 

isAlphabetized: boolean]; 

RecPointer: TYPE s long pointer to MyRec; 

-map the file.... 

space: Space.lnterval <~NSSegment.Map[...]; 

~ use somePtr to access the coritents of the file as if 
-it were a variable of type RecType. Notice that we never 
-actually declare a variable of type RecType; we just use the 
-virtual memory as if it were a variable of RecType. 
somePtr: RecPointer <-LOOPHOLE[space.pointer]; 
somePtr.isEnglish <-false; 



This example sets up a record structure with three fields, maps 
a file to virtual memory, and then access the virtual memory as 
it were a variable of type RecType. Figure 13.3 illustrates this 
idea. 



map the file with NSSegment.Map 




VM 



space. pointer 



LOOPHOLE somePtr into space. pointer 



^^^^^^^^ 

""^m^mi LONG POINTER 



VM 



BOOL 



BOOL 



space. pointer 



somePtr 



Figure 13.3: Mapping a file and then LOOPHOLING 



13.3.3 Updating the file 



When you are finished with a mapped space, you should call 
Space. Un map: 

Space.Unmap: PROCEDURE [ 
pointer: LONG POINTER, 
returnWait: space. ReturnWa it <- wait] 
RETURNS [nil: long pointer]; 
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pointer denotes your virtual memory interval; returnWait 
specifies whether Pilot backs up dirty pages before returning to 
the client, (wait is currently the only value implemented; you 
should always just default this parameter.) Unmap returns a nil 
pointer; the idea is that you should do something like this: 

myPointer <-Space.Unmap[myPointer]; 

Unmap will write any dirty pages, and free the virtual memory 
that the space occupies, as illustrated in Figure 13.4. You 
should call Unmap regardless of whether you have made any 
changes. 




...frees the interval of 
virtual memory, and 
ends the mapped 
relationship. 



file 




Figure 13.4: Unmapping 



You can also back up dirty pages manually, with the procedure 
Space.ForceOut: 

Space.ForceOut: PROCEDURE [interval: Space. Interval]; 

You can call this procedure at any time to force your changes 
to be written to the disk. How often you call ForceOut is a 
judgment call based on the importance of the data that you 
are manipulating and the probability of a machine failure. 



13.3.4 Complete mapping example 



Here is a program fragment that keeps a record of the 
ingredients that are used to make various kinds of drinks. It 
maps the data file to virtual memory in order to add a new 
drink. 
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NSSegmentExample: program imports NSFile, NSSegment, 
Space ■ 

BEGIN 

--max number of drinks that can be on file 
maxNumberOfDrinks: cardinal a 255; 
-max number of ingredients in a given drink 
numOflngredients: cardinal s 32; 
---A drink 

Drink: TYPE m packed array [0.. numOflngredients) of bool]; 

—the main data structure. Count keeps track of the number 

-of drinks currently on file; bitmap is an array of drinks,. 

ContentBitMap: type a record [ 

count: CARDINAL, - number of drinks in file 
bitmap:, ARRAY [0.. maxNumberOfDrinks) of Drink; 

BitMapPtr: TYPE = long pointer to ContentBitMap; 



-This procedure is called when it is time to add a new drink 
-to the database 
WriteContents: public proc[ 
drink: Drink , 

fileReference: NSFiie.Reference] = { 

-get the size of the file in pages. If the file is not an exact 
-multiple of the page size, include an extra partial page. 
sizelnPages: long cardinal <- 

siZE[ContentBitMap] / Environment.wordsPerPage; 
IF siZE[ContentBitMap] mod Environment.wordsPerPage # 0 

THEN sizelnPages <- sizelnPages* 1; 

-open the file 

file: NSFiie. Handle <-NSFiie.OpenByReference[fileReference]; 

-- map file to VM so we can write to it. Specify entire file as 

-origin; allow write access. 

space: Space. Interval <-NSSegment.Map[ 

origin: [file:file, base: 0, count: sizelnPages], 

access: NSFiie.full Access]; 

- use contentPtr to access the contents of the file as if 
-it were a variable of type ContentBitMap 
contentPtr: BitMapPtr «-LOOPHOLE[space. pointer]; 

-set index to be the next available slot for new drink 
index: cardinal <-contentPtr.count; 
-update count of drinks. Raise a signal if we're out 
—of room. 

contentPtr.count^- index + 1; 
iFcontentPtr.count > maxNumberOfDrinks 
THEN SIGNAL FileFull; 

- write ingredients of new drink to mapped contents file 
for i : CARDINAL IN [O..number0flngredients) do 

contentPtr.bitmap[index][i] <- drink[i]; 

ENDLOOP; 

~ unmap the interval, thus writing changes back to the file 
space.pointer Space. Unmap[space. pointer! 

space. Error = > continue]; 
NSFiie.Close[file:file]}; 

END... 
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The WriteContents procedure is called with two arguments: a 
new drink, and a reference to the file where the data is stored. 
WriteContents should add the new drink to the file. 

The first step is to map the file to virtual memory. To do this, 
we get a handle to the file, and set up an origin that represents 
the entire file. We then call NSSegment.Map to map the file to 
virtual memory. 

Once we have the interval of virtual memory, we loophole 
space. pointer into a pointer to our record structure. We can 
then access the virtual memory as if it were a variable of type 
ContentBitMap. We add the new drink to the file, and then call 
Unmap to write the changes back out to the file. Finally, we call 
NSFile.Close. 



1 3,4 Copyin/ CopyOut 



NSSegment.CopyIn and NSSegment.CopyOut allow you to copy 
from virtual memory to a file and vice versa. Thus, for example, 
you can map one file to virtual memory and then use the 
CopyOut operation to copy the information to a second file. 
Figure 13.5 illustrates this idea. 



filei 



tHXHXHXHMXMleXH! 



\ \ 



Map a portion of filei to VM 



VM 











Copy Out from VM 






into file2. 



file2 



MOOOOOQHHOHOOHHHMW 



Figure 13.5: The CopyOut operation 



An example of a situation in which you would want to use one 
of the Copy procedures is in copying portions of files. You 
might first map a file to a space and then call CopyOut to copy 
part of its contents into another file. 

Here is some code that uses CopyOut to copy one entire file to 
another: 
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Copy: PROCEDURE[fromFile, toFile: NSFile. Handle] 

RETURNS[C0piecl: BOOLEAN <- false] » 
BEGIN 

ENABLE {NSFiie.Error ■ > goto Exit; 
Space.Error ■ > goto Exit;}; 

BEGIN 

pages: NSSegment.PageCount; 

length: NSSegment.PageCount <-NSSegment.GetSizelnPages[ 

file: fromPile]; -length of original file 
fromOriqin: NSSegment.Oriqin <— \ 

file: fromFile, 

base: 0, 

count: length]; 
toOriqin: NSSegment.Oriqin <- \ 

file: toFile, 

base: 0, 

count: length]; 

-map original file to virtual memory 

space: space.lnterval <- NSSegment.Map [ 

origin: fromOrigin]; -default access is read 
NSSegment.SetSizelnPages[file: toFile, pages: length]; 

--copy from first file to second file 
paqes <- NSSeqment.CopvOut [ 

pointer: space.pointer, origin: toOrigin]; 
IF pages ■ length then copied <- true; 
space.pointer ^ space. Unmap[space. pointer]; 
end; 

EXITS Exit a > return; 
end; 



13.5 Summary 



To establish a mapping between a file and an interval of virtual 
memory, call NSSegment.Map. Map takes several parameters, the 
most important of which are origin, and access, origin specifies 
the portion of a file that you are interested in, and access 
specifies whether or not you can write the space. Map returns a 
space.lnterval, which describes a portion of virtual memory. 

You can then use loophole to access that interval as if it were 
the data structure of your choice. When you are through 
making changes, you need to call Space.Unmap to write your 
changes out to the file. If you want to save your information at 
an intermediate point, you can call space.ForceOut. 

You can also use NSSegment.CopyIn and NSSegment.CopyOut to 
copy data from one file into another via virtual memory. For 
example, you could first map a file to a space and then call 
CopyOut to copy part of its contents into another file. 

For more information on the topics in this chapter, consult the 
Space chapter of the Pilot Programmer's Manual and the 
NSSegment chapter of the Filing Programmer's Manual. 
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Finally, here is the complete filing example that we promised 
you. The code creates the tool illustrated in Figure 13.6 



p| File Tool ^^^^^^^^ Close f Another ]|^Lo ad f Save J □ J^S | 


m 




+ 

t 


FileName 




Version 0 





Figure 13.6: The File Tool 



With this tool, the user can create a new file in the system 
catalog by filling in a name and version, typing the desired 
contents of the file in the space below the version field, and 
then invoking Save. Similarly, he can load an existing file with 
the Load command or delete a file with the Destroy command. 

DIRECTORY 

Atom, 

Attention, 

BWSFIieTypes, 

Context, 

Form Window, 

Catalog, 

Environment, 

Heap, 

MenuData, 

NSFlle, 

NSSegment, 

NSString, 

NSFlieStream, 

Process, 

Space, 

StarWindowShell, 

Stream, 

TIP, 

Window, 

XChar, 

XString; 

BWSFIIeTooi: program 

IMPORTS Attention, Catalog, Context, FormWindow, Heap, 
MenuData, NSFile, NSFileStream, NSSegment, Space, 
StarWindowShell, Stream, XString shares XString a 

BEGIN 

fileType: NSFiie.Type = ^OOWI; - arbitrary 
Items: TYPE = {nameltem, versionltem,textltem}; 
context: context.Type «- Context. UniqueType[]; 
bodyWindowDlms: window.Dims a [1000,1000]; 
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Data: TYPE a long pointer to DataObject; 

DataObject: type = record [ 
fiieHandle: NSFiie.Handle <-NSFiie.nullHandle, 
space: Space.lnterval <- Space. nulllnterval, 
string: xstring.ReaderBody <-null]; 

"Procedures 

- delete the specified file 
Destroy: MenuData.MenuProc = { 
noName: xstring.ReaderBody 

xstring.FromSTRING ["No name specified"L]; 
name: xstring.ReaderBody; 
fiieName: NSFiie.Handle; 
body: window.Handle <— 
StarWindowShell.GetBody [[wi ndow]] ; 

--get riame and versior) from form window 
name FormWindow.GetTextltemValue[ 

body, 0, Heap.systemZone]; 
iFxstring.Empty[@name] then 
{Attention.Post[@noNa me] ; return ; }; 

-get a handle to file and then delete it 
fiieName «-Cataiog.GetFile[name: @name 

! NSFile.Error ■ > goto Exit]; 
NSFiie.DeieteHileName! NSFiie.Error ■ > G0T0Exit2]; 

-set the file name and contents to NIL in form window. 
Formwindow.SetTextltemValue[ 

body, Items.nameltem.ORD, nil]; 
Formwindow.SetTextltemValue[ 

body,ltems.textltem.ORD, nil]; 

exits 

Exit ■ > { 

error: xstring.ReaderBody 

xstring.FromSTRING ["NSFiie create error"L]; 
Attention.Post[@error] ; return ; }; 
ExitZ a > { 

error2: xstring.ReaderBody «- 

xstring.FromSTRING ["NSFiie Delete error"L]; 
Attention.Post[@error2]; return;} }; 

~ return the context for this window body 
GetContext: proc [body: window.Handle] 

RETURNS [data: Data] = { 

data <-Context.Find[context, body]; 

IF data ■ NIL THEN error; 

RETURN [data]}; 

-register "File Tool" command in Attention Menu 
Init: PROC = { 

fileTool: xstring.ReaderBody <- 

xstring.FromSTRING["FileTool"L]; 
Attention.AddMenultem [MenuData.Createitem [ 
zone: Heap.systemZone, 
name: ©fileTool, 
proc: MenuProc] ]}; 
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- get the contetns of the file by mapping the file to VM 

- and then LOOPHOLING a pointer to the characters. 
-Display contents of file in window. 

Load: MenuData. Men uProc a { 
body: window. Handle <- 

StarWindowShell.GetBody [[wi ndow]] ; 
data: Data <-GetContext[body]; 
sizelnBytes: long cardinal <-0; 
deleted: xstring.ReaderBody ^ 

xstring.FromSTRING ["File Deleted"L]; 
name: xstring.ReaderBody; 
version: long integer; 
myBlock: Environment.Block <- [NIL, 0, 0]; 

begin enable { 
Space.Error = > 

{error: xstring.ReaderBody 

xstring.FromSTRING ["Space Error"L]; 
Attention.Post[@error]; 
GOTO Exit;}; 

NSFiie.Error a > {NSFileError[error]; goto Exit}; 
xstring.lnvaHdNumber,xstring.Overflow » > 

{error: xstring.ReaderBody 

xstring.FromSTRING ["Space Error"L]; 

Attention. Post[@error]; 

GOTO Exit} }; 

-get name and version from input in form window 
name <-Formwindow.GetTextltemValue[ 

body. Items. nameltem.ORD, Heap.systemZone]; 
version 'e-Formwindow.GetlntegerltemValue[ 

body, Items.versionltem.ORD]; 

-open file 

data.fileHandle <— Open[name, version]; 
iFdata.fileHandle = NSFiie.nullHandle then return; 

-map entire file to virtual memory 
data.space '<-NSSeqment.Map[ 
orig in: [ 

data.fileHandle, 

0, 

NSSegment.GetSizelnPages[data.fileHandle]], 
swapUnits: [uniform[4]]]; 

-access virtual memory as if it is a Environment.block 
sizelnBytes 

NSSegment.GetSizelnBytes[data.fileHandle]; 
myBlock.stoplndexPlusOne ♦-CARDiNAL[sizelnBytes]; 
myBlock. blockPointer <— data. space. pointer; 
data.strinq <-xstrinq.FromBlock[block: mvBlockl; 

-display contents of file in form window and then close 

-everything up. 

FormWindow.SetTextltemValue[ 

body, Items.textltem.ORD, ©data. string]; 
data.space. pointer ^ 

Space.Unmap[data.space. pointer]; 
NSFiie.Close[data.fileHandle]; 
EXITS Exit = > return; 
END }; 
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~ Build the window and menu commands 
MenuProc: MenuData.MenuProc a { 
another: xstring.ReaderBody <- 

xstring.FromSTRING["Another"Ll; 
load: xstring.ReaderBody <- 

xstring.FromSTRING["Load"L]; 
save: xstring.ReaderBody <- 

xstrlng.FromSTRING["Save"L]; 
destroy: xstring.ReaderBody 

xstring.FromSTRING["Destroy"L]; 
fileTool: xstring.ReaderBody ^ 

xstring.FromSTRI NG [" Fi le Tool " L] ; 

~ Create the StarWindowShell. 
shell: StarWindowShell.Handie a 

starwindowSheii.Create [name: @fileTool]; 

~ Create a body window inside the StarWindowShell. 
body: window.Handle a starwindowSheii.CreateBody [ 
sws: shell, 

box: [ [0,0], bodyWindowDims]]; 
-add commands 

z: UNCOUNTED ZONE StarWindowShell. GetZone [shell]; 
items: array [0..4) of Menuoata.ltemHandle [ 
MenuData.Createltem [ 

zone: z, name: ©another, proc: MenuProc], 
MenuData.Createltem [ 

zone: z, name: @load, proc: Load], 
MenuData.Createltem [ 

zone: z, name: @save, proc: Save], 
MenuData.Createltem [ 

zone: z, name: ©destroy, proc: Destroy]]; 

-create menu of commands 
myMenu: MenuData.MenuHandle = 
MenuData.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items]]; 

-add commands to header 
starWindowShell.SetRegularCommands [ 
sws: shell, commands: myMenu]; 

- Allocate data and "hang it off the body window" 
Context.Create [type: context, 

data: Heap.systemZone.NEw[DataObject «- []], 

proc: Context.SimpleDestroyProc, 

window: body]; 

--make the body window a form window 
FormWindow.Create [window: body, 

makeltemsProc:MakeFormltems, 

zone : Heap.systemZone] ; 

~ Put the StarWindowShell on the screen. 
StarWindowSheil.Push [shell] }; 
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"MakeltemsProc for form window. Note that there are 
-three fields: a text field for the name of the file, an 
-integer item for the version, and another text item for 
-the contents of the file. The contents text item does not 
-have a box around it, so it is not visible on the screen. 
MakeFormltems: FormWindow.MakeltemsProc = { 
nameTag: xstring.ReaderBody 

xstrmg.FromSTRING["FileName"L]; 
versionTag: xstring.ReaderBody <- 

xstring. FromSTRI NG ["Version " L] ; 

Form Window. Ma keTextltemE 
window: window, 
myKey: items. nameltem.ORO, 
tag: ©nameTag, width: 300]; 

FormWindow.Makelntegerltem[ 
window: window, 
myKey: Items.versionltem.ORD, 
tag: ©versionTag, width: 200]; 

FormWindow.MakeTextltem[ 
window: window, 
boxed: false, 

myKey: Items.textltem.ORD, 
width: 600] }; 



-- print NSFile error messages 

NSFiieError: procedure [error: NSFiie.ErrorRecord] s 

BEGIN 

accessError: xstring.ReaderBody ^ 

xstring.FromSTRING ["accessError"L]; 
attributeTypeError: xstring.ReaderBody <- 

xstring.FromSTRING ["attributeTypeError"Ll; 
handleError: xstring.ReaderBody <- 

xstring.FromSTRING ["handleError"L]; 
spaceError: xstring.ReaderBody <- 

xstring.FromSTRING ["spaceError"L]; 
undefinedError: xstring.ReaderBody <— 

xstring.FromSTRING ["undef inedError"L]; 

WITH mvError: error select from 

access ■ > Attention.Post[@accessError]: 
attributeType, attribute Value a > 

Attention.Post[@attributeTypeError]; 
handle ■ > Attention.Post[@handleError]; 
space B > Attention.Post[@spaceError]; 
undefined a > Attention.Post[@undefinedError]; 
endcase; 
end; 
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This chapter discusses how to use the Selection interface, which 
defines the abstraction of the user's current selection. 

There are two kinds of programs that use the Selection 
interface: requestors and mar^agers. Requestors are programs 
that want to obtain the value of the current selection; 
managers are programs that own and change the current 
selection. For example, the desktop implementation is a 
selection manager: when the user selects an icon, the desktop 
implementation must implement that selection. A printer icon, 
on the other hand, is a requestor: it needs to know the value of 
the currently selected icon so that it can print the correct file, 
but it does not change the value of that selection. 

This chapter covers only requestors; for information on 
selection managers you will have to consult the Selection 
chapter of the Viewpoint programmer's Manual. 



14.1 Converting the selection 



When the user selects something and then asks an application 
to operate on that selection, the application needs to get the 
value of the current selection. An application typically can't act 
on all possible selections, however. For example, if the user 
selects something, presses copy, and then selects a printer icon, 
the printer application can only print the selection if it is a 
document, a folder, an interpress master, or the like. If the 
selection is a paragraph of text, or another printer icon, then 
the printer cannot accept the selection. Similarly, a document 
editor might only be interested in the selection if it is a string. 

Thus, a selection requestor is only interested in the selection if 
it can obtain that selection in a particular format. To request 
the selection as a particular data type, you call 
Seiection.Convert: 

Selection.Convert: PROCEDURE [ 
target: Seiection.Target, 
zone: uncounted zone <- nil] 
RETURNS [value: Seiection.Value]; 

Seiection.Target: TYPE ■ machine dependent{ 

window(O), shell, subwindow, string, length, position, 
integer, interpressMaster, file, fileType, token, help, 
interscriptScrlpt, InterscriptFragment, serializedFile, name, 
firstFree,last(1777B)}; 

Seiection.Value: TYPE a RECORD [value: long POINTER, . . .]; 

Seiection.nuliValue: Seiection.Value ■ [value: NIL,...]; 
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Convert is a request to produce the selection as an object of 
TYPE target (Note that the target is just the type, not the actual 
data object.) 

When a requestor calls Convert, the Selection implementation 
will call the selection manager to obtain the selection in the 
desired format. The selection manager determines whether or 
not it supports conversion to a particular target; most 
managers only support a limited number of targets. For 
example, if the selection is a text string, the manager might 
implement conversion to string and perhaps to integer, but 
probably not to file or fileType. 

If the conversion is possible, the return parameter value.value 
will be a long pointer to the converted selection. (There are 
also other fields in value, but they are for the use of selection 
managers only. You don't have to worry about them for now.) 
If the conversion is not possible. Convert will return nullValue. 

Notice that target is an open-ended enumeration of data 
types. The Selection interface defines a number of common 
targets, and the values that each returns. If the target type that 
you need is not among those defined in this interface, you can 
define a new target with a call to Selection.UniqueTarget. See 
the Viewpoint Programmer's Manual for details. 

Here is a list of the most frequently used targets and the results 
that they return; for more information on any of the values in 
Seiection.Target, see the Selection chapter of the ViewPoint 
Programmer's l\/lanual: 

window returns a window.Handie for the window that 

contains the current selection. 

shell returns a starWindowSheii.Handle for the shell 

that contains the current selection. 

String returns an xstnng.Reader representing the 

text of the current selection. 

length returns a long pointer to long cardinal 

containing the number of characters in the 
selection. 

integer returns a long pointer to long integer 

containing the selection as a number. 

interpressMaster returns a stream. Handle to an interpress 
master. 

file returns a long pointer to NSFile.Reference for 

the file associated with the selection. 

fileType returns a long pointer to NSFiie.Type for the 

file associated with the selection. 

Here is an example of calling Selection. Convert with a target 
type of String: 
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streamHandle: stream. Handle < — GetStreamToSomeFile--; 
xfo: XFormat.Object <-XFormat.StreamOb]ect[streamHandle]; 

- Convert returns nullValue if manager can't convert selection; 

- nullValue has a value.value of NIL 
savedString: Selection. Value Selectlon.Con vert[stri nq] ; 
iFsavedString.vaiue ■ nil then { 

Stream. Delete[streamHandle]; return}; 
XFormat.Reader[@xfo, loophole[ 

savedString.value, xstring.Reader]]; 
stream.Delete[streamHandle]; 
Selection. Free[@savedStri ng] ; 

This example sets up a stream to a file, creates an XFormat 
object that contains the stream, and then calls Convert to try to 
convert the selection to a string. If the conversion is not 
possible, the procedure just returns. If the conversion is 
possible, it sends the string to the stream, and then returns, 
deleting the stream and calling Selection. Free on the way out. 

You must call Selection. Free when you are through with the 
selection; this allows the selection manager to deallocate any 
Storage that it may have allocated: 

Selection. Free: PROCEDURE [v: seiection.ValueHandle]; 

Note: To guarantee that the user cannot alter the selection 
while you are reading it, you should only read the selection 
from within the Notifier. If you are not responding to a user 
command when you need to get the value of the selection, you 
should use a periodic notifier. See Chapter 9, TIP, for more 
information on the Notifier and periodic notifiers. 



14.2 Resource management 



An important rule for requestors is that the selection belongs 
to the manager, not the requestor. Convert returns a read-only 
value: you can look at the data in value, but you cannot modify 
it. If you want to use the selection later, or pass it to another 
process, you must first copy the selection using Seiection.Copy, 
Selection. Move, or Seiection.Copy Move: 

Seiection.Copy: PROCEDURE [ 
v: Seiection.ValueHandle, 

data: long pointer] a inline {CopyMove[v,copy, data]}; 

Selection. Move: PROCEDURE [ 
v: Seiection.ValueHandle, 

data: long pointer] = inline {CopyMove[v,move, data]}; 

Seiection.Copy Move: Selection.ValueCopyMoveProc; 

Seiection.ValueCopyMoveProc: TYPE = procedure [ 
v: Seiection.ValueHandle, op: CopyOrMove, 
data: long pointer]; 

Selection.CopyOrMove: type = {copy, move}; 

Seiection.ValueHandle: long pointer to seiection.Value; 

The meaning of data depends on the target. It is often used as 
the storage for the destination of the copy. See the Viewpoint 
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Programmer's Manual for the exact meaning of data for a 
particular target. 

Here is an example of calling Copy: 

GetSeiectedFlie: PROC RETURNS [stream: stream. Handle nil] a { 
element: selection. Value <-Seiection.Convert [target: file]; 
IF element. value a nil then signal FileProblem 
ELSE begin -conversion was successful 

ref : LONG pointer to NSFiie.Ref erence; 

handle: NSFiie.Handle; 

dir: NSFiie.Reference 

starDesktop.GetCurrentOesktopFile[]; 

Seiection.Copy[@element, @dir]; 

ref element.value; 

handle: NSFiie.Handle ^NSFiie.OpenByReference [ 

reference: ref | iNSFiie.Error = > signal FileProblem]; 
stream <-NSFiieStream.Create[handle]; 
Seiection.Free[@element]; 
end; 

}; 

This example obtains the value of the currently selected file. If 
the selection cannot be converted to a file, then raise a signal 
indicating that there is a problem. If there is no problem, then 
the next step is to copy the selection. 

When the selection is a file, the data parameter to Copy should 
be a LONG POINTER TO NSFiie.Reference to the directory in which 
you want to store the file. (Remember, you need to consult the 
Viewpoint Programmer's Manual to find out what data should 
be for a given selection type.) 

In this case, we call starDesktop.GetCurrentDesktopFlle to get a 
reference to the current desktop, and then call Copy, passing in 
the desktop reference as the data parameter. Once we have 
copied the selection, we open the file, get a stream to the file, 
call Selection. Free, and then return. 

If the selection is a string, you can use standard String routines, 
such as xstring.CopyReader or xstring.CopyToNewWriterBody or 
the like, to copy the string instead of using Selection.Copy. For 
example: 

GetStrIng: public procedure [] returns 
[string: xstring.ReaderBody] a { 

value: Selection.Value '<-Selection.Convert[string]; 
string^iFvalue.value a NIL 

THEN GetConstantString[] 

ELSE xstring.CopyReader[LOOPHOLE 
[value.value,xstring.Reader],sysZ] | ; 
Selection. Free[@value]; 

}; 

This example gets the currently selected string by calling 
Convert with a target type of string. If the return value is NIL 
(the conversion did not succeed), then call the procedure 
GetConstantString to get a default constant value. Otherwise, 
call CopyReader to copy the string, call Free to allow the 
manager to deallocate storage, and then return. 
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Note that in the case of the target type stream, calling Copy is 
particularly important. In this case, you cannot even read the 
stream without copying it, because reading the stream alters 
the stream state and thus alters the stream.Object to which the 
stream.Handle points. Thus, you must copy the stream handle 
before using the stream. (Even after you have copied the 
stream, you can only read it; the stream handle has read-only 
access.) Once you have copied the handle, you are responsible 
for the stream and you must call stream. Delete when you are 
through with it. 

In all cases you must call Seiection.Free regardless of whether you 
copy the selection. If you do copy the selection, you own the 
resources, and you should eventually free them. If you don't 
copy the selection, the manager owns the resources but you 
should still call Free to let him know that he can free the 
resources. 



14.3 Can you convert the selection? 



Since all selections do not convert to all target types, you might 
want to find out whether a particular conversion is possible, 
and possibly get an indication of how difficult the conversion 
would be before you actually do the conversion. This is useful 
in cases where the conversion is expensive (for example, when 
the target type is an interpress master), and you want to find 
out whether or not the conversion is possible before you waste 
too much time. To find out this information, you can call 
Selection.CanYouConvert. 

Seiection.CanYouConvert: procedure [ 
target: Seiection.Target, 
enumeration: boolean <- false] 
RETURNS [yes: boolean] s inline { 

RETURN[HowHard[target, enumeration] # impossible]}; 

The enumeration parameter allows you to ask if the manager 
supports enumerating the selection (see the next section.) 

CanYouConvert returns a boolean specifying whether the 
manager supports conversion to the specified type. Note that 
this is just an indication of whether the manager believes it is 
possible; it is not a guarantee that the conversion will actually 
work. The manager might still run into some unexpected 
difficulties, such as running out of disk space or the like. 

If you want a specific indication of how hard the conversion 
will be, instead of an indication of whether it is possible, you 
can call HowHard directly: 

Selection.HowHard: PROCEDURE [ 
target: seiection.Target, 
enumeration: boolean «- false] 
RETURNS [difficult: Selection. Difficulty]; 

Selection.Difficulty: TYPE ■ {easy, moderate, hard, impossible}; 

Here is an example of calling CanYouConvert. This type of 
procedure is generally called from the canYouTakeSelection 
arm of a containee.GenericProc. This code is interested in the 
selection only if it is an integer or a string. If the selection 
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manager does not implement conversion to any of these types, 
then this application cannot accept the selection. 

CanlTake: procedure RETURNS[yes: boolean] & 

BEGIN 

~ Take anything that is a string or integer 
return[ 

Seiection.CanYouConvert[ 

target: string, enumeration: false] or 
Seiection.CanYouConvert[ 

target:integer,enumeratlon:FALSE] ]; 

end; 

Note also that there is a Selection. Query procedure, which 
effectively allows you to ask multiple CanYouConvert 
questions at the same time. See the Viewpoint Programmer's 
Mani/a/ for details. 



14.4 Enumerating selections 



A selection is often a collection of items (several files in a 
folder) or a single large item that can be split up (such as a long 
string.). In particular, there is a limit on the size of string that 
Convert can return. A call to Convert[string] never produces a 
string longer than Selectlon.maxStringLength (200) characters; if 
the selection is a longer string you will have to treat it as a 
sequence of strings. 

A requestor can convert each part of such a selection 
individually by calling Selection. Enumerate. 

Seiection.Enumerate: procedure [ 
proc: seiection.EnumerationProc, 
target: Seiection.Target, 
data: Seiection.RequestorData <-nil, 
zone: uncounted zone <- nil] 
RETURNS [aborted: boolean]! 

Seiection.EnumerationProc: TYPE * procedure [ 
element: Selection. Value, 
data: Seiection.RequestorData] 
returns [stop: boolean 4- false]; 

Seiection.RequestorData: TYPE = long pointer; 

Calling Enumerate will result in a call to proc for each piece of 
the selection. Each time it calls proc, the Selection 
implementation will pass data as a parameter. This data is for 
your own use; it can be nil if you like. 

Calling Enumerate is thus roughly equivalent to calling Convert 
for each individual piece. (If the manager can't convert the 
selection to the specified target, proc won't be called.) If you 
want to stop the enumeration, you can set stop to be true in 
your proc. 

Here is an example of using Enumerate: 
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Absorb: PROCEDURE[ciata: Containee.DataHandle] 
RETURNS[absorbed: boolean <- false] ■ 

BEGIN 

"This is the enumeration proc. It will be called once for 
-each piece of the selection. It appends elementvalue to 

the end of the stream. 
AbsorbString: Selection. EnumerationProc > begin 

xFormat.Reader[@xfo, LOOPHOLE[element. value]]; 

Selection. Free[@element]; 
end; 

set up a format object whose output sink is a stream 
xfo: XFormat.Object; 

fileStream: NSFiieStream. Handle <-GetStream [data]; 

-set current position to be the end of the file 

stream.SetPosition[ 

fileStream, NSFiieStream.GetLength[fileStream]]; 

xfo <- XFormat.StreamObject [fileStream]; 
"if the manager can convert the selection to a series of strings, 
-then call Selection. Enumerate; if it can be converted to a 
-single string, call AbsorbString directly. 
IF seiection.CanYouConvert [string, true] then 

[] «-Selection.Enumerate[AbsorbString, string, nil] 
ELSE { 

v: Selection. Value = Selection.Convert[string]; 

IF v.value #nilthen[] «-AbsorbString[ v,nil]}; 
Stream. Delete[fileStream]; 
end; 

The main code of Absorb starts by setting up a format object 
with a stream as its output sink. The next step is to call 
CanYouConvert to find out if it is possible to get the selection 
as a simple string. If it is, then call the procedure AbsorbString 
to add the string to the stream. 

If isn't possible, call CanYouConvert again with enumeration 
TRUE to find out if it it can be converted to a series of strings. If 
it can, call Enumerate. This will result in a call to AbsorbString 
for each string in the sequence. AbsorbString can then add the 
stri ngs to the stream one at a ti me. 



14.5 Summary 



Applications that need to obtain the value of the current 
selection are requestors; applications that own and control the 
current selection are managers. This chapter discussed only 
requestors. 

The principle action that requestors perform is asking for the 
selection in a particular form by calling Convert. The Selection 
interface defines a number of common target types for the 
selection; you can also define your own target. When a 
requestor calls Convert, the Selection interface in turn calls the 
selection manager to determine whether the conversion is 
possible. If the conversion is possible. Convert returns a long 
pointer to the selection. If the conversion is not possible. 
Convert returns nullValue. 

The value that Convert returns belongs to the manager, not 
the requestor. If you want to use the value of the current 
selection after you leave the Notifier, or if you want to pass it 
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to another process, you must first copy the selection with Copy, 
Move, or CopyMove. 

When you are through with the selection, you should call Free 
to free the resources associated with the selection. You need to 
do this regardless of whether or not you have copied the 
selection. 

If you want to find out how difficult a particular conversion will 
be before you actually attempt it, you can call CanYouConvert 
or HowHard. These procedures provide information on 
whether the selection manager believes the conversion is 
possible; they do not produce a guarantee that the conversion 
will be successful. 

You may also have to obtain the selection as a series of objects 
rather than a single object. For example, if the user copies a 
folder to the printer, the printer implementation will need to 
call Enumerate to get an interpress master for each of the 
documents in the folder. This procedure is often called when a 
call to CanYouConvert says that the manager supports 
conversion to the specified type, but a call to Convert fails. 



14.6 Exercise 




To move a checker, you select the desired checker with the 
mouse and then select a new location for that checker. When 
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you select a new square, the checker is erased from the 
previous square and drawn in the new square. 

If you don't finish a game, you can store it in a file by selecting 
a file on the desktop and invoking "StoreGame." To resume an 
old game, select the file that contains the game and invoke 
"ResumeOldGame." If the selection contains several files, the 
tool will enumerate the available files, and you can choose the 
game that you want to play from the Attention window. 

Standard checkers rules apply. The tool checks the legality of 
moves, although it does not keep track of whose turn it is. 

Your assignment is to write the code for the procedures 
ResumeOldGame and GetSelectedFlie in the module 
CheckersSelectionlmplTemp. 

ResumeOldGame gets the current selection, converts it into a 
file, and reads the data in that file. GetSelectedFlie is called 
when the tool needs a stream handle to a file; it converts the 
current selection to a file. 

You will also need the following modules: 

CheckersDefs 

CheckerslmpI 

CheckersMsglmpI 

CheckersBitmaplmpI 

Checkers.config 
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Notes: 
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15 



ICON 
APPLICATIONS 



This chapter describes how to write an application that runs 
from an icon instead of from a command in the Attention 
Menu. 



15.1 Overview 



icons on the desl<top are part of what is referred to as the "user 
illusion." The user sees various icons, such as printers and 
documents, and associates those icons with certain functions 
and files. He can open a document, copy a document to the 
printer, look at properties of the document, and so forth. 

From the client's point of view, however, an icon is a picture 
that represents a file. The desktop itself is a directory with 
children; there is an icon for each child of the desktop. Every 
application that uses icons must reg/ster with the desktop by 
specifying the file type on which it operates and providing 
procedures to display the icon on the screen and implement 
operations on that icon. 

When the user first logs in, the desktop enumerates its children 
and calls the appropriate application to display an icon on the 
desktop. When the user selects an icon and wants to operate 
on it, the desktop determines the file type for that icon, 
associates the file type with an application, and then calls that 
application to perform the operation. 

To write an icon application, you need to register with the 
desktop and write the appropriate call back procedures. 



1 5.2 Registering with the desktop 



To register an application with the desktop, call 
Containee.Setlmplementation: 

containee.Setlmplementation: procedure[ 
NSFiie.Type, 

Containee.lmplementation] 
RETURNS[containee.implementation]; 

Containee.lmplementation: TYPE ■ record [ 
implementors: long pointers nil, 
name: xstring.ReaderBody <-xstring.nullReaderBody, 
smallPictureProc: Containee.SmallPictureProc <- nil, 
pictureProc: Containee.PictureProc «- nil, 
convertProc: seiection.ConvertProc ^ nil, 
genericProc: containee.GenericProc <- nil]; 
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Setlmplementation associates an Implementation record with 
a file type, and returns the Implementation previously 
associated with that file type. 

implementors is a pointer for client-specific data; you can store 
the data of your choice here, name is a name for the objects on 
which the application operations, such as "spreadsheet." You 
can ignore both of these fields for now. 

pictureProc is a call back procedure that displays the icon 
picture on the screen. Section 1 5.2. 1 discusses PictureProcs. 

smallPictureProc is similar to pictureProc, except that it creates 
a miniature version of the icon picture. Section 15.2.2 discusses 
SmallPictureProcs. 

genericProc is a call back procedure that determines how the 
icon implements the "generic" operations copy, move, open, 
and PROPS. Section 15.2.3 discusses GenericProcs. 

convertProc is a call back procedure that determines whether 
the manager can convert the file to a particular type. This is 
important when you are managing the selection. For now, just 
use Containee.DefaultFileConvertProc, which implements 
conversion to the types file and fileType. See the 
ViewPointProgrammer's Manual for more information. 

Here is an example of calling Setlmplementation: 

-register application with desktop. Called from mainline code. 
-myFileType is a global variable 
Setlmplementation: proc = { 

newlmpi: Containee.lmplementation <- 
Containee.Getlmplementation[myFileType]; 

oldlmpi «(-zone.NEw[containee.[mplementation <- newlmpi]; 

newlmpl.convertProc^-containee.DefaultFileConvertProc; 

newlmpl.genericProc <- GenericProc; 

newlmpi. pictureProc ^ PictureProc; 

newlmpl.smallPictureProc <- SmallPictureProc; 

[] >-containee.Set[mplementation[myFileType, newlmpi] }; 

This example declares the local variable newlmpi, and then 
calls Getlmplementation to store the existing implementation 
in newlmpi. It then allocates the variable oldlmpi (a global 
LONG POINTER TO Containee.lmplementation), and stores the old 
implementation in this variable as well. At this point, newlmpi 
and oldlmpi contain the same information. 

The next step is to change the convertProc, genericProc, 
SmallPictureProc, and pictureProc in newlmpi, and then store 
the new implementation. Notice that we discard the results of 
the call to Setlmplementation; since we have already retrieved 
the value of the old implementation. 

newlmpi is a local variable. It doesn't need to be global, 
because you can always get this information with a call to 
Getlmplementation. oldlmpi is a global variable because you 
will need to access it from another procedure. (There is an 
example in the next section that shows why you need oldlmpi.) 
oldlmpi is a pointer to an Implementation rather than an 
Implementation to minimize storage in the global frame. 
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15.2.1 PIctureProcs 



The pictureProc field of an Implementation is a call back 
procedure that displays an icon on the screen. There are two 
possible ways to define an icon picture: you can include a 
pictureProc in your Implementation or you can use icon files. 
An icon file associates an icon bitmap with a file type; when 
the application is loaded, the icon file in the application folder 
is opened to read the bitmap and display the icons. Chapter 1 6, 
Application Folders, discusses how to use icon files. 



A pictureProc is of type Containee.PictureProc: 

Containee.PictureProc: TYPE a PROCEDURE [ 
data: Containee.DataHandle, 
window: window.Handle, 
box: Window. Box, 
old, new: Containee.PictureState]; 



Containee.DataHandle: TYPE s LONG POINTER TO Containee.Data; 



Containee.Data: TYPE a RECORD [ 

reference: NSFiie.Reference <-NSFiie.nullReference]; 



Containee.PictureState: TYPE = {garbage, normal, highlighted, 
ghost, reference, referenceHighlighted}; 

old and new describe the state of the icon. An icon generally 
has slightly different pictures for different states, such as when 
the icon is selected (highlighted) or open (ghost.) Figure 15.1 
illustrates different states of the document icon. 
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Figure 15.1 Icons 



window and box describe the area of the screen where the 
icon is to appear; you should pass these parameters to the 
Display routine that you call to actually display the icon. 

data allows you to distinguish among many files of the same 
file type. You can create slightly different icons for various files 
associated with an application. For example, all documents 
associated with the document editor have the same file type 
(and hence the same icon shape), but generally different 
names and contents. Thus, the document editor includes the 
name of the file on each icon. 



To get the name of the file from the NSFiie. Reference, you don't 
need to use NSFiie routines. Instead, you should use 
Containee.GetCachedName: 
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Containee.GetCachedName: procedure [ 
data: Containee.DataHandle] 

RETURNS [name: xstring.ReaderBody, ticket: containee.Ticket]; 
Containee.Ticket: type[2]; 

data is the data parameter to the PictureProc. The return 
parameters are the file name and a Ticket. A Ticket ensures 
that no other process can change the name of the file while 
you are looking at it. When you are through, you need to 
return the ticket: 

Containee.ReturnTicket: PROCEDURE [ticket: Containee.Ticket]; 

Here is a PictureProc that puts the name of the file on the icon: 

"This procedure describes the actual bitmap. 
InitBlgPicture: proc ■ { 

mylconPic<-space.ScratchMap[1]. pointer; 

mylconPic | [1 77777B, 1 77777B, 000063B, ...] }; 

-This procedure paints the name of the file on the icon 
PaintlconName: proc [window: window.Handle, 

box, textBox: window.Box, name: xstring.Reader] = { 
[] <-simpieTextDisplay.StringlntoWindow [ 
string: name, 
window: window, 
place: textBox. place, 
lineWidth: textBox.dims.w] }; 

PictureProc: Containee. PictureProc ■ { 

-textBox describes where the title is to appear. textBox is 

--relative to box, which is in turn relative to window. 

textBox: window.Box [[x:7, y:10],[w:55, h:36]]; 

name: xstring.ReaderBody; 

ticket: Containee.Ticket; 

IF new a garbage THEN return; 

box.dims <- [64,64]; —size of the icon 

-Retrieve the name of the file whose reference is data. 
[name, ticket] «-containee.GetCachedName[data]; 

< < Display the icon. Call InitBlgPicture to display the icon, 
and PaintlconName to add the name of the file. > > 

select old FROM 

garbage,ghost ■ > { 
Display.Bitmap[ 
window: window, 
box: box, 

bitmapBitWidth: 64, 
address: [mylconPicture, 0, 0]; 
PaintlconName[window, box, textBox, @name]}; 
endcase; 

SELECT new FROM 

highlighted ■ > Dispiay.lnvert[window, box]; 
ghost a > {Dispiay.White[window, box]; 

PaintlconName[window, box, textBox, ©name]}; 
endcase; 

-return the ticket from the call to GetCachedName 
containee.ReturnTicket[ticket] }; 
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InitBigPicture is the procedure that contains the actual bits for 
the icon picture. See Appendix B, Icon Editor, to find out how 
to generate the bits for your desired picture. 

Inside the PictureProc, the first step is to call GetCachedName 
to retrieve the name of the file. The next step is to display the 
icon picture with a call to Display.Bltmap and to display the 
name of the icon with a call to PaintlconName. If the icon state 
is highlighted, invert the icon picture; if the icon state is ghost, 
paint a white version of it. After it paints the icon, it returns the 
Ticket that it got in the call to GetCachedName, and then 
returns. 



A Small PictureProc is similar to a PictureProc, except that it 
defines a small (13X13 pixels) version of the icon. For example, 
this tiny icon will be used when the icon is inside a folder. 
When you open a document inside a folder, the title for the 
folder will display the tiny icon for both the folder and the 
document, as illustrated in Figure 15.2. 



AsmallPictureProc is of type Containee.SmallPictureProc: 

Containee.SmallPictureProc: type = procedure [ 
data: Containee.DataHandle <-niu 
type: NSFile.Type «-Contalnee.ignoreType, 
normalOrReference: containee.Pictu restate] 
RETURNS [smallPicture: xstring.Character]; 

To create a tiny icon, you create the bitmap and then create a 
new character out of that bitmap. You create a new character 
by calling simpieTextFont-AddCiientDefinedCharacter: 

simpieTextFont-AddClientDefinedCharacter: procedure [ 
width, height: cardinal, 
bitsPerLine: cardinal, 

bits: LONG POINTER, 

offsetlntoBlts: cardinal <- 0, 
RETURNS [xstring.Character]; 

This procedure takes a bitmap and creates a character out of it. 
Here is a code fragment that illustrates how to do a tiny icon: 



15.2.2 SmallPktureProcs 




1 5.2: Document header with tiny icons 
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smallPic: xstring.Character <-xstring.nullChar; 

SmallPicture: Containee.SmallPictureProc = {return [smallPic]}; 

-Call this procedure directly from mainline code, or from 
-Setlmplementation (which is called from mainline.) 
InltSmallPicture: procedure a { 

bits: array [0..1 3) of Word <- [1 77777B, . . .]; 
IF smallPic a xstring.nullChar then 

smallPic<^simpieTextFont.AddClientOefinedCharacter[ 
width: 13, 
height: 13, 
bitsPerLlne 16, 
bits: ©bits] }; 

You can also initialize the bitmap directly in your 
SmallPictureProc, if you like. 



15.2.3 Generic procs 



When the user selects an icon, the desl<top implementation 
determines the icon's file type, calls Getlmplementation to find 
the Implementation associated with that file type, and then 
calls the genericProc in the Implementation. The genericProc 
thus implements various icon operations: for example, it 
determines what happens when the user move or copys 
something to your application. 

A genericProc is of type Containee.GenericProc: 

Containee.GenericProc: type = procedure [ 
atom: Atom, atom, 
data: Containee. Data Handle, 
changeProc: Containee.ChangeProc <~nil, 
changeProcData: long pointer <- nil] 
returns [long unspecified]; 

Containee.ChangeProc: type = procedure [ 
changeProcData: long pointers- nil, 
data: Containee.DataHandle, 
changedAttributes: NSFiie.Selections <- [], 
noChanges: boolean <- false]; 

atom specifies which operation to perform. Notice that the 
return result is unspecified; different operations return 
different results. Here is a list of the most common atoms and 
the results that you should return for each: 

CanYouTakeSeiection 

The user has selected something, pressed copy or move, and 
then selected your file. You should determine whether you 
can accept the selection (by calling Seiection.CanYouConvert, 
Selection.HowHard or the like) and return a long pointer to 
BOOLEAN indicating whether the conversion is possible. 

Open 

The user has selected your icon and invoked OPEN. You 
should create a StarWindowShell and return a handle to it. 
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Props 

The user has selecetd your icon and invoked PROPS. You 
should create a property sheet and return a handle to it. 

TakeSelection 

The user has selected something, pressed move, and then 
selected your icon. You should implement the operation 
(how you do this depends on the application) and then 
return a long pointer to boolean indicating whether the 
operation was successful. 

TakeSeiectionCopy 

This atom is just like TakeSelection, except that the user 
pressed copy instead of move. 

Here is a simple example of a GenericProc: 

GenericProc: Containee.GenericProc = { 
select atom from 
open ■ > return[ 

Defs.MakeShell[data, changeProc, changeProcData]]; 
props a > return[ 

Defs.MakePropertySheet[ 

data, changeProc, changeProcData]]; 
ENDCASE ■> RETURN[oldlmpl.genericProc[atom,data, 
changeProc, changeProcData]] }; 

Note the endcase, which calls the old implementation for any 
atoms that the select statement doesn't handle. (This is why 
you need to store the old Implementation when you call 
Setlmplementation.) In most cases, the old implementation 
will be the default implementation supplied by Containee, 
which displays an appropriate message to the user. 

Notice also that we pass changeProc and changeProcData as 
parameters to MakeSheli and MakePropertySheet. The next 
section discusses ChangeProcs in detail. 

15.2.3.1 ChangeProc 



Depending on which operation you are performing, executing 
the GenericProc can potentially change the value of some of 
the file's attributes. This is not a problem for the application 
itself: if it does something that alters an attribute, it is 
responsible for updating the attributes accordingly. There are 
times, however, when a change to an application's file affects 
other applications. 

For example, suppose the user presses props on a document in a 
folder, uses the property sheet to change the name of the 
document, and then selects Done. The document application 
can respond to the change in its implementation of the Done 
command, but the folder must also recognize the change so 
that it can update the name of the document inside the folder. 

A ChangeProc is a procedure that a "container" (such as a 
folder) supplies to a "containee" (such as a document). The 
containee is expected to call the ChangeProc to allow the 
container to recognize changes. Note that the containee 
implementation does not provide the ChangeProc, and never 
even sees it; the containee just has to call the ChangeProc. 
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In this case, the icon application is the "containee," and the 
desktop is the "container." Thus, the desktop implementation 
supplies a ChangeProc as a parameter to every GenericProc; 
the application must in turn call that ChangeProc. 

Since the purpose of a ChangeProc is to allow the container to 
act on changes, you might think that you only need to call the 
ChangeProc if you change attributes. However, calling the 
ChangeProc also allows the container to deallocate the 
changeProcData. Thus, you must call the ChangeProc 
regardless of whether you have changed any attributes. 

Therefore, you need to ensure that every arm of your 
GenericProc results in a call to the ChangeProc. If the operation 
can't affect any attributes, you can call the ChangeProc 
immediately, before you implement the operation. If the 
operation can potentially change attributes, however, you 
need to call the ChangeProc after the operation completes. 
This sometimes requires some careful planning to make sure 
that you have access to the ChangeProc when you need it. 

For example, consider the following GenericProc: 

GenericProc: Containee.GenericProc ■ { 

SELECT atom FROM 

open ■ > return[ 

Defs.MakeShell[data, ChangeProc, changeProcData]]; 
props = > return[ 

Defs.MakePropertySheet[ 
data, ChangeProc, changeProcData]]; 
canYouTakeSelection = > { 

changeProc[changeProcData: changeProcData, 

noChanges: true]; 
RETURN @[false]}; 
endcase b> RETURN[oldlmpl.genericProc[atom,data, 
ChangeProc, changeProcData]] }; 

This GenericProc calls the ChangeProc directly from the 
canYouTakeSelection atom, since executing that arm cannot 
change any attributes. Note that the ©[false] value returned is 
a pointer to a global variable false, which is a boolean declared 
to be FALSE. Using a local variable is not good enough, since the 
storage must exist after return from this procedure. 

The open and props branches, however, can both potentially 
change attributes, so we pass changeProc and changeProcData 
to MakeShell and MakePropertySheet, which should call 
changeProc when the operation completes. 

This is harder than it sounds, however. In the case of 
MakePropertySheet, you really need to call the ChangeProc 
when the user invokes Done or Cancel, not when you have just 
put the property sheet on the screen. Similarly, in the case of 
MakeShell, you need to call the ChangeProc after the shell is 
put away, not when it is first created. 

For example, here is a program fragment that shows how 
MakePropertySheet should handle the changeProc: 
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-Globals, including record to contain change procedure 
DataObject: type = record [ 
fh: NSFile.Handie, 

chanqeProc: Containee.ChanqeProc <-nil , 

chanqeProcData : long pointer <- nil ] ; 
Data: TYPE ■ long pointer to DataObject; 
zone: uncounted zone <-Heap.Create[initial:1]; 

< < This procedure is called from the GenericProc, with 
parameters changeProc, changeProcData, and data. It allocates 
a record for the changeProc, and calls PropertySheet.Create, 
passing the data record as clientData. > > 
MakePropertySheet: public proc[ 

data: containee.DataHandle, 

changeProc: Containee.ChangeProc <-nil, 

changeProcData: long pointers- nil] 

RETURNS [pSheetShell: starwindowSheii. Handle] a { 
-allocate data. Note that fh is an open file handle. 
myData: Data <r- zone.NEW [DataObject <- [ 

f h : NSFiie.OpenByReference[data. reference], 

chanqeProc: chanqeProc . 

chanqeProcData: chanqeProcData ]]; 

< < Call Create. Note the clientData parameter, which is the 
ChangeProc. > > 

pSheetShell <- PropertySheet.Create [ 
formWindowltems: Makeitems, 
menultemProc: MenultemProc, 
menultems [done: true, cancel : true], 
size: size, 
title: ©title, 

placeToDisplay: placeToDisplay, 

f orm Wi ndowltemsLayout : Form window.def a u ItLayoutProc, 

display: false, 

clientData: mvData] >; 
"See chapter 7, Form Windows 
Makeitems: Formwindow.MakeltemsProc = {...}; 

< KCalled when user invokes Done or Cancel. clientData is the 
myData record allocated in MakePropertySheet. To use this 
data, you need to declare a local variable and then assign 
clientData to it. > > 

MenultemProc: PropertySheet.MenultemProc ■ { 
mvData: Data ^clientData; 
SELECT menultem from 
done a > { 

ok <- ApplyAnyChanges[formWindow, myDataj.ok; 

zone.FREE[@myData]; 

NSFiie.Close[myData.fh]; 

return [ok]}; 

--call the change procedure even though there are no 

-changes 

cancel ■ > { 

data: containee.Data ^NSFiie.GetReference[myData.fh]]; 
IF myData.changeProc # nil then mvData.chanqeProc [ 

chanqeProcData: mvData.chanqeProcData, 

data: @data, 

chanqedAttributes: [], 

noChanqes: true]; 
NSFiie.Close[myData.fh]; 
zone.FREE[@myData]; 
RETURN [ok: true]}; 
endcase s > RETURN [ok: false] }; 
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"Called when the user invokes Done. Updates actual attributes 
ApplyAnyChanges: PROC[fw: window.Handle, myData: Data] 

RETURNS [ok: boolean] b { 

attrList: array [0..1) of NSFiie.Attribute; 

changed Attributes: NSFiie.Selections []; 

ctChangedAttrs: cardinal <-0; 

--if nothing's been changed, call ChangeProc and return 
IF NOTFormWindow.HasAnyBeenChanged[fw] then { 
IF myData.changeProc # nil then 
mvData.chanqeProc [ 

c hanqeProcData: mvData.chanqeProcData . 

noChanqes: true] ; 
return [ok: true] }; 

< KSomething has been changed. Loop through to find 

out what has changed, update the attributes, and then call 

the changeProc...> > 

for myltem: Items in Items do 

itemKey: Formwindow.ltemKey = myltem. ord; 
-if this item hasn't changed, then loop 
if not Formwindow.HasBeenChanged [fw, itemKey] 
THEN loop; 

-the item has changed, so update appropriate attributes 
SELECT myltem from 
name ■ > { 

rb: xstring.ReaderBody <- 

FormWindow.LookAtTextltemValue [fw, itemKey]; 
ns: NSString.String <-xstring.NSStringFromReader [ 

@rb, localZone]; 
Formwindow.DoneLookingAtTextltemValue [ 

fw, itemKey]; 
attrList[ctChangedAttrs] [name[ns]]; 
changedAttributes.interpreted[name] <-true; }; 
endcase; 

ctCliangedAttrs f-ctCliangedAttrs + 1; 
endloop; 

-if any attributes have changed, then store new attributes 
-and then call change proc 
IF CtChangedAttrs > Othen{ 

data: Containee.Data [ NSFile.GetReference [myData.fh] ]; 
NSFiie.ChangeAttributes [ 

myData.fh, descriptor [©attrList, ctChangedAttrs]]; 
NSFiie.ClearAttributeList [ 

DESCRiPTOR[@attrList, CtChangedAttrs]] ; 
-call change proc 
IF myData.changeProc # nil then 

myData.changeProc[ 

myData.changeProcData, ©data, changedAttributes]; 



-no attributes have changed, but still have to call 
changeProc 
else 

if myData.changeProc # nil then 
myData.changeProc[ 
changeProcData:myData.changeProcData, 
noChanges: true]; 
RETURN [ok: true]; 

}; 
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The PROPS arm of the generlcProc calls MakePropertySheet, 
passing in changeProc and changeProcData. 
MakePropertySheet creates the property sheet but does not 
implement the Done and Cancel commands, so you need to 
pass the changeProc on to the procedure that will be in control 
when the user finishes making changes and invokes Done. 

To do this, allocate a record that contains the change 
procedure. The storage for this record should come from a 
heap, not from a local or global frame. (The local frame doesn't 
work because the storage isn't permanent enough; the global 
frame doesn't work because there may be more than one 
property sheet open for a given application.) 

Once you have stored the changeProc in the record, you can 
pass a pointer to that record as the clientData parameter to 
PropertySheet.Create. You should also pass MenultemProc as the 
procedure to be called when the user invokes Done or Cancel; 
clientData will be a parameter to this procedure. 

Inside the MenultemProc, store clientData into a variable of 
type Data. (Mesa's type checking prevents you from accessing it 
directly.) If the command was Cancel, call the changeProc and 
return. If the command was Done, call ApplyAnyChanges, 
which figures out if there were any changes and acts 
accordingly. Notice that we call the changeProc in all cases. 

The MakeSheil procedure will be somewhat similar. You need 
to pass the changeProc to MakeSheil, but you should call it 
from your TransltionProc. (The potential changes to the file 
will occur after MakeSheil has completed.) The standard way to 
handle this is to pass the changeProc to MakeSheil, and then 
store it in the shell's context. You can then retrieve the context 
from the TransltionProc and call the changeProc from there. 



1 5.3 The Prototype interface 



When you write an icon application you don't place the icon 
directly on the desktop; that is the user's prerogative. Instead, 
you put your icon in the Prototype folder. 

You create and manipulate prototype files using the ViewPoint 
Prototype interface. Its main procedures are Find and Create: 

Prototype.Find: PROCEDURE [ 
type: NSFile.Type, 
version: Prototype.Version, 
subtype: prototype.Subtype «-0, 
session: NSFiie.Session <-NSFiie.nullSession] 
RETURNS [reference: NSPiie.Reference]; 

Prototype.Create: procedure [ 
name: xstring. Reader, 
type: NSFile.Type, 
version: Prototype.Version, 
subtype: Prototype.Subtype «-0, 
size: long cardinal <-0, 
isDirectory: boolean false, 
session: NSFile.Session <-NSFile.nullSession] 
RETURNS [prototype: NSFiie.Handle]; 
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type, subtype, and version uniquely identify a given prototype 
file, subtype distinguishes objects of the same type; version 
helps determine if the prototype is current. 

Find returns a reference for the file with the specified type, 
version, and subtype. If the file doesn't exist, Find returns 
NSFiie.nullReference. Create creates a file in the Prototype 
catalog with the specified name, type, version, subtype, size (in 
bytes), and isDlrectory attribute. The following code fragment 
shows typical usage of Prototype. Find and Prototype.Create; 

-This procedure is called from the mainline code 
FindOrCreatelconFile: procedure [name: xstring.ReaderBody, 
type: NSFile.Type, version: cardinal] = { 
IF Prototype.Find[type, version] ■ NSFiie.nullReference 
THENNSFi[e.Close[Prototype.Create[ 

name:@name, type:type, version:version]] }; 

The first step is to call Find to see if the file already exists. If not, 
(Find returns NSFiie.nullReference), then call Create, which 
creates the file, opens it, and returns a file handle. In this 
example, we just close the file immediately, since we don't 
need the open file handle for anything. 



15.4 Summary 



To write an icon application, you need to do the following : 

• Write a GenericProc to implement move, copy, etc. Make 
sure that you call the ChangeProc (sooner or later) from 
each arm of the GenericProc. 

• Initialize the atoms you recognize in the GenericProc. 

• Write a PictureProc to display the icon, and optionally a 
SmallPictureProc for the tiny version of the icon. 

• Call Containee.Setlmplementation to register the 
application with the desktop. Your Implementation 
should include at least a GenericProc and a PictureProc. 

• Put a copy of the icon in the Prototype folder using 
either Prototype.Find or Prototype.Create. 

Here is a program fragment that illustrates these steps: 

-global data 

smallPic: xstring.Character <-xstring.nullChar; 
oldlmpi: LONG POINTER TO Containee.lmplementatlon; 

-called from the mainline code to put icon in prototype folder 
FindOrCreatelconFile: procedure a { 

mh: XMessage.Handle ■ Defs.GetMessageHandlef]; 

name: xstring.ReaderBody <-xMessage. Get [ 

mh,Defs.MessageKey.prototypeFileName.ORD]; 

version: cardinal «- 1 ; 

IF Prototype. Find[type, version] = NSFiie.nullReference 
THENNSFile.Close[Prototype.Create[ 

name:@name,type:type, version:version]] }; 
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"implement open and props; all other atoms go to the endcase. 
GenericProc: Containee.GenericProc « { 

SELECT atom FROM 

open a > RETURN[Defs.MakeShell[ 

data, changeProc, changeProcData]]; 
props s > return[ 

Defs.MakePropertySheet[ 

data, changeProc, changeProcData]]; 
ENDCASE m > RETURN[oldlmpl.genericProc[ 
atom, data, changeProc, changeProcData]] }; 

-called from mainline code to intialize atoms 
I nit Atoms: proc ■ { 

open: Atom.ATOM <- Atom.MakeAtom["Open"L]; 

props: Atom.ATOM <- Atom.MakeAtom["Props"Ll}; 

InitBigPicture: proc = { iconPicture <- ...set up bitmap}; 

InitSmallPicture: procedure ■ { 

bits: ARRAY [0..13) of Word <- [177777B, . . .]; 
iFSmaliPic b xstring.nullChar then 

smallPic<-simpieTextFont.AddClientDefinedCharacter[ 
width: 13, 
height: 13, 
bitsPerLine 16, 
bits: ©bits] }; 

-draw the icon 

PictureProc: Containee.PictureProc = { 

textBox: window.Box [[x:7, y:10],[w:55, h:36]]; 

name: xstring.ReaderBody; 

ticket: Containee.Ticket; 

IF new a garbage THEN return; 

box.dims^- [64,64]; 

[name, ticket] <-containee.GetCachedName[data]; 

select old FROM 

garbage, ghost a > {Dispiay.Bitmap[...]; 

PaintlconName[window, box, textBox, ©name]}; 
endcase; 

SELECT new FROM 

highlighted » > Display.lnvert[window, box]; 
ghost - > { 

Dlsplay.White[window, box]; 
PaintlconName[window, box, textBox, ©name]}; 
endcase; 

Containee.ReturnTicket[ticket] }; 

-register application with the desktop 
Setlmplementation: proc « { 

newlmpi: containee.lmplementation <— 

Containee.Getlmplementation[myFileType]; 

oldlmpi <— zone. NEw[containee. Implementation <— newlmpi]; 

newlmpl.convertProc^-Containee.DefaultFileConvertProc; 

newlmpl.genericProc <- GenericProc; 

newlmpi. pictureProc <— PictureProc; 

newlmpl.smallPictureProc SmallPicture; 

[] <-Containee.Setlmplementation[myFileType, newlmpi] }; 

SmallPicture: Containee.SmallPictureProc a {return [smallPic]}; 
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-mainline code 

lnitAtoms[]; 

FindOrCreatelconFile[]; 

InitBigPictureH; 

lnitSmallPicture[]; 

Setlmplementation[]; 



15.5 Exercise 



The exercise for this chapter is a Tic-Tac-Toe game, illustrated 
in Figure 15.3. 



PI Tic Tac Toe Close f User Starts j Computer Starts | Confirm Move |n| S jH 





















Figure 15.3 The Tic Tac Toe application 



To start a game, select either Computer Starts or User Starts. If 
you select Computer Starts, the program will make a random 
move on the board and wait for you to respond. If you select 
User Starts, the program waits for you to make the first move. 

To make a move, select a box and invoke Confirm Move. You 
cannot select a square that is already occupied. You can start a 
new game at any time with User Starts or Computer Starts. 

The module TicTacToeToollmplTemp.mesa implements the 
tool code and the user commands. The application currently 
runs from the Attention menu; you should modify this module 
so that the tool will run from an icon on the desktop. This will 
involve writing the procedures GenericProc, 
FindOrCreatelconFile, InitBigPicture, PaintlconName, and 
Setlmplementation and modifying the MakeShell procedure. 
You will also need the following modules: 

TicTacToeDefs TicTacToeMsglmpI 
TicTacToelmpI TicTacToe.config 
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Once you have an application running to your satisfaction, it is 
time to package it as a finished application. Packaging consists 
of taking auxiliary data out of the code modules and putting it 
in separate data files. For example, if you have designed a new 
icon for your application (other than the ones in 
Standard. icons), you should put the bitmap for that icon in an 
icon file. If your application posts messages you should put the 
messages in a separate message file rather than in an 
implementation module. This approach has the advantage that 
it allows you to modify the data files without recompiling the 
application. This is particularly useful for applications that are 
potentially multinational. 

Once you have moved the data into separate data files, you 
need to group the data files and the object files together into a 
single coherent object, so that the user doesn't have to concern 
himself with obtaining all the component files. Viewpoint 
provides the notion of an application folder ior this purpose. 



16.1 Building an application folder 



An application folder consists of object files and associated 
data files. Note that the term application folder is a bit of a 
misnomer, since an application folder is not the same thing as a 
standard folder on the desktop (i.e., they have different file 
types.) An application folder must must have at least one 
object file, and may have any or all of the following data files: 

• A message file 

• An icon file 

• One or more TIPC files 

• A keyboard file (if the application uses a keyboard that is 
not in the standard keyboard file ) 

An application folder can also include other private data files, 
such as translation tables or the like. For example, if your 
application translates ASCII to some other code, such as 
EBCDIC, you might wish to include a translation table for this 
purpose. 

This chapter discusses only how to build the application folder 
once you have the data files; it does not discuss how to 
generate the data files. The appendices of this manual describe 
some tools that are available for creating message and icon 
files; Chapters, TIP, discusses .TIPC files. 
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1 6.1 .1 Application description files 



In addition to the actual files that constitute the application, 
an application folder must contain an Application Description 
File (ADF). This file describes the components of the 
application; having a separate description file means that you 
don't need to hardcode the names of the data files into the 
application. 

When you write an application, you should include the 
capability of having the data files either bound in an 
application folder or stored in the system folder. Typically, 
developers store their data files in the system folder during 
development (and use the WorkstationProfile as an ADF), and 
then create their own application folder as the final step. The 
examples later in this chapter show how to write code that 
allows either of these approaches. 

An ADF consists of the application's internal name, the names 
of the data files, the loading priority of the application, and 
any other entries an application requires. The application's 
object files are listed in starting order. All other entries may 
occur in any order. 

The loading priority is important only for an application that 
depends on another application. In such a situation, the 
application that must start first has a lower priority number 
than the dependent application; the loader starts applications 
in increasing priority number order. If your application has no 
dependencies, use a priority of zero (the default.) 

The easiest way to create an ADF is to copy the 
WorkstationProfile, modify it, and then rename it. The syntax 
for an ADF follows that of an option file. (Other examples of 
option files are the Workstation Profile and the User Profile.) 

Here is an example of an ADF: 

[SampieApplicatlon] 

bed: Sample.bcd - Object file 
MessageFile: Sample.messages 
IconFile: Sample. icons 
KeyboardFilerSample.keyboards 
TIPFile: Sample.TIP - Really a TIPC file 
Priority: 0 

Only the section name and bed entry are mandatory. The 
section name (SampieApplicatlon) is the internal name of the 
application; the code for the application uses this name to 
reference the application folder. The internal name never 
changes. The application also has an external name, which 
appears on the folder. The external name can be changed, 
making multilingual conversion easier and more complete. An 
external name for an ADF is typically something like 
ApplicatlonName.adf. 

Figure 16.1 illustratesthe complete syntax for an ADF: 
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<ADF> ::= [Opplication internal name>]<keyword series> | nil 

< keyword series > : : a < keyword series > < component > | < component > 


< component > 


: ■ < object file > | < message file > | < icon file > | 

< keyboard f i le > | < TIPC Fi le > | < priority > | < requires > 


< object file > 


: ■ bed: <any legal NSFile name>.bcd 


< message file > 


::- < Entry Identifier >: <any legal NSFile name> 


<icon file> 


:b < Entry Identifier >: <any legal NSFile name >. icons 


< keyboard file> 


:a < Entry Identifier >: <any legal NSFile name> 


<TIPCfile> 


::= < Entry Identifier >: <any legal NSFile name > 


< priority > 


: a Priority: < Integer > 


< requires > 


::■ Requires: < Required application internal Name 1 >,. , 
< Required application internal Name n> 



Figure 16.1 ADF syntax 



Note that the < Entry Identifier >s can be any identifier, but 
should indicate the type of entry. For example, the entry name 
for translation tables could be TransTable. The standard 
identifiers are MessageFile, IconFile, KeyboardFile, and TIPFile. 

The Requires entry lists the internal names of applications that 
must be loaded and started for this application to run. 



16.2 Modifying the code 



Once you have created your data files and written an ADF for 
them, you must change your code to access the data files. 
Typically, you start with tlie internal name of the application, 
and then you need to perform the following steps. 

1. Call AppiicationFoider.FromName to get an NSFiie.Reference to 
the application folder. This procedure returns 
NSFile. nullReference if it can't find the specified folder. 

AppiicationFoider.FromName: procedure [ 
internalName: xstring.Reader] 
RETURNS [applicationFolder: NSFiie.Reference]; 

2. Open the folder with NSFile.OpenByReference. 

3. Get a reference to the ADF within the specified folder with a 
call to ApplicationFolder. FindDescriptionFile: 

AppiicationFolder.FindDescriptionFile: procedure [ 
applicationFolder: NSFiie.Handle] 
RETURNS [descriptionFile: NSFiie.Reference); 
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4. Parse the ADF to find the name of the data file that you are 
interested in. To do this, call OptionFile.GetStringValue: 

optionFiie.GetStringValue: procedure [ 
section, entry: xstrmg. Reader, 
callBack: procedure [value: xstring.Reader], 
index: cardinal <-0, 

file: NSFiie.Reference «- NSFiie.nullReference]; 

GetStringValue calls callBack with the value of a string entry, 
section is the internal name of the ADF that you want to 
read; entry is the specific entry that you are interested in. If 
the entry is there, GetStringValue will call back to callBack, 
passing in the value of that entry, file is a reference to the 
file that contains the specified ADF. 

The following sections show examples of these steps for 
retrieving a message file, a TIP file, and an icon file from an 
ADF. 



16.2.1 Message Files 



Whenever an application uses messages, it must provide a way 
to access the message handle. Recall that when you use a 
message implementation, you call XMes$age.AllocateMessages 
and xMessage.RegisterMessages to retrieve the messages. (See 
Chapter 3, Strings and Messages, if you want to review 
message beds.) If your messages are in a file, however, you 
retrieve them using XMessage.MessageFromFile or 
xMessage.MessagesFromReference 

XMessage.MessagesFromFile: procedure [ 
fileName: long string, 
clientData: XMessage.ClientData, 
proc: XMessage. Destroy MsgsProc] 
returns [msgDomains: XMessage.MsgDomains]; 

XMessage.MessagesFromReference: procedure [ 
file: NSFiie.Reference, 
clientData: XMessage.ClientData, 
proc: XMessage.DestroyMsgsProc] 
RETURNS [msgDomains: XMessage. Msg Domains] ; 

XMessage.MsgDomains: TYPE a LONG DESCRIPTOR FOR ARRAY OF 

XMessage. MsgDomain; 

xMessage.MsgDomain: TYPE s record [ 
applicationName:xstring.ReaderBody, 
handle: XMessage.Handle]; 

MessagesFromFile gets the messages from the file named 
fileName in the system folder, while MessagesFromReference 
gets the messages from the file whose reference is file. When 
you are through with the messages, you must call 
FreeMsgDomainsStorage: 

XMessage. FreeMsgDomainsStorage: procedure [msgDomains: 
XMessage.MsgDomains]; 
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Here is an example of how to write code that uses a message 
file. The code reads the ADF to find the name of the message 
file, and then uses XMessage routines to access the messages. 

~ File: SampleMsgFilelmpl.mesa 

- Copyright (C) 1985 by Xerox Corporation. All rights reserved. 

DIRECTORY 
...-{ 

- Data 

h: XMessage.Handle <-nil; 

iocaiZone: uncounted zone <-Heap.systemZone; 

-- Procedures 

DeleteMessages: proc [clientData: XMessage.ClientData] ■ 

{}; 

GetMessageHandle: public proc returns [xMessage.Handle] ■ 

{RETURN[hl}; 

< < This procedure is called from mainline code. Its job is to call 
MessagesFromReference to initialize the value ofh so that 
other procedures can call GetMessageHandle and be able to 
access the messages. The hard part is getting the file parameter 
to MessagesFromReference. To do this, first call FromName to 
get a reference to the folder for the appication, and then call 
GetMessageFlleRef to find the message file within that folder. 
>> 

InitMessages: procedure s { 

internalName: xstring.ReaderBody <- 

xstring.FromSTRING ["SampleBWSApplication"L]; 
msgDomains: XMessage.MsgDomains nil; 
msgDomains <-XMessage.MessagesFromReference [ 

file: GetMessageFlleRef 

[AppiicationFoider.FromName[@internalName]], 

clientData: NIL, 

proc: DeleteMessages]; 
h <- msgDomains[0]. handle; 
XMessage.FreeMsgDomainsStorage [msgDomains]; 

}; 
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< < This procedure is called from InitMessages. It declares the 
internal procedure FindMessageFileFromName, and then 
initializes folderHandle and adf. If there is no ADF for the 
application, use the system folder and the WorkStationProfile; 
otherwise, call FindDescriptionFlie to find the appropriate 
ADF. The final step is to call GetStringValue to get the name of 
the message file. GetStringValue results in a call back to 
FindMessageFile, which finally gets a handle to the message 
file. > > 

GetMessageFileRef : procedure [folder: NSFiie. Reference] 
RETURNS [msgFile: NSFiie.Reference <- 
NSFiie.nuliReference] ■ { 

folderHandle: NSFiie.Handle <-NSFiie.nullHandle; 
adf: NSFiie.Reference NSFiie.nuliReference; 
internalName: xstring.ReaderBody <- 

xstrlng.FromSTRING ["SampleBWSAppllcation"L]; 
messageFlle: xstring.ReaderBody f- 

xstring.FromSTRING ["MessageFile"L]; 

FindMessageFileFromName: procedure [ 
value: xstring.Reader] = { 

nssName: NSString.String <-xstring.NSStrlng From Reader 

[r: value, z: localZone]; 
msgFileHandle: NSFiie.Handle <-NSFiie.nuliHandle; 
~ do NSFIIe.Find in case the name has an asterisk in it 
msgFileHandle <-NSFiie.Find [directory: folderHandle, 

scope: [filter: [matches[ 

attribute: [name[nssName]]]]] ! 
NSFiie.Error a > {msgFileHandle <-NSFiie.nullHandle; 

continue}!; 
-- No message file 

IF msgFileHandle s NSFiie.nullHandle then error; 
msgFile <-~NSFiie.GetReference [msgFileHandle]; 
NSFiie.Close [msgFileHandle]; 
NSString.FreeString [z: localZone, s: nssName]; 

}; 

IF folder a NSFiie.nuliReference THEN { 

~ No application folder, so use the system catalog and the 

-Workstation Profile 

folderHandle <- catalog. Open 

[BWSFileTypes.systemFileCatalog]; 

adf <r- OptionFile.GetWorkstationProf ile []} 

ELSE{ 

- There was an application folder, so use the folder and 
-- the adf inside it. 

folderHandle ^NSFiie.OpenByReference [folder]; 

adf ^AppiicationFoider.FindDescriptionFile 
[folderHandle]}; 
OptionFiie.GetStringValue [section: ©internalName, 

entry: @messageFile, 

callBack: FindMessageFileFromName, 

file: adf]; 
NSFiie.Close [folderHandle]; 

}; 

~ Mainline code 

lnitMessages[]; 

}.. 
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The mainline code calls InitMessages, which calls 
xMessage.MessagesFrom Reference to obtain the messages for 
the application. To call MessagesFromReference, however, it 
needs a reference to the file containing the messages. To get 
this reference, it calls AppiicationFoider.FromName to get a 
reference to the folder and then calls GetMessageFlieRef. 

GetMessageFileRef checks to see whether folder is 
nullReference. If it is, it sets folder to the system catalog, and 
adf to the workstation profile. If there is an ADF for the 
application, however, it calls AppiicationFoider.FindDescrlptionFlie 
to get a reference to the ADF (within the specified folder.) 

Once folderHandle and adf are initialized, the next step is to 
call OptionFiie.GetStringVaiue to parse the ADF. If there is a 
messages entry in the option file, this procedure results in a call 
back to FindMessageFileFromName. This procedure just gets a 
handle to the file that contains the messages; this handle 
(msgFlie) is returned up to InitMessages to be the file 
parameter to MessagesFromReference. 

Once you have edited the message implementation to use 
message files, you still need to use the Message Tools to 
actually create the messages file. See Appendix C, Message 
Tools, for information on how to use these tools to create a 
message file. 



16.2.2 Private TIP file 



This example shows how to write code that puts a TIP file in the 
ADF instead of putting it directly in the code. Note that the 
actual data file that you put in the ADF should be a .TIPC file, 
but that you should name it .TIP in the ADF entry. 

sampleTIPTable: TiP.Table <-nil; 

< < This procedure is called from the mainline code. It calls 
AppendTIPFileName to get the complete path name for the TIP 
file, and then calls CreateTable to generate the runtime TIP 
table for the program's use. > > 
InitTIPTable: procedure = { 

-separator is a I character, used for separating directories 
separator: xchar.Character s loophole[ 

NSFileName.nameVersionPairSeparator]; 
pathName: xstring.WriterBody ^xstring.NewWriterBody[ 

40, zone]; 

AppendTIPFileName [@pathName]; 
sampleTIPTable <-TiP.CreateTable [ 

file: xstring.ReaderFromWriter [@pathName]]; 
xstring.FreeWriterBytes [@pathName]; 

}; 
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< < The job of this procedure is to get a full path name for the 
TIP file and store it in the writer parameter. This involves 
parsing the ADF. > > 

AppendTIPFileName: PROCEDURE [writer: xstring.Writer] = { 
separator: xchar.Character = loophole 

[NSFiieName.nameVersionPairSeparator]; 
internalName: xstring.ReaderBody <-xstring.FromSTRING 

["SampleBWSApplication"L]; 
tipFile: xstring.ReaderBody ^-xstring.FromSTRING [ 

"TIPFile"L]; 
folderHandie: NSFiie.Handle; 
-get a reference to the folder 

folderRef : NSFiie.Reference <-AppikationFoider.FromName 

[@internalName]; 

-call back procedure that is called if there is a TIP entry in 
-the ADF. Adds the name of the ADF to the path name in 
—writer. 

AppendName: PROCEDURE [value: xstring. Reader] a { 
xstring.AppendReader [to: writer, from: value]; 

}; 

-If there is no application folder, then use a default, 
~ hard-coded TIP file name. 

IF folderRef s NSFiie.nuliReferenceTHEN{ 
xstring. AppendSTRING [ 

writer, "SampleBWSApplication.TIP"L]; 
return}; 

- ELSE (there is an ADF, so parse it to get the 

- name of the TIP file. 

folderHandie <-NSFi[e.OpenByReference [folderRef]; 
-put the name of the folder in the writer 
AppendFolderName [folderHandie, writer]; 
-add a directory separator 
xstring.AppendChar [to: writer, c: separator]; 
-parse the ADF to get the name of the TIP entry. If the entry 
-is there, this results in a call to AppendName, which adds 
-the name of the file to create a full path name. 
optionFiie.GetStringValue [ 

section: @internalName, 

entry: @tipFile, 

callBack: AppendName, 

file: AppiicationFoider.FindDescriptionFile [folderHandie]]; 
NSFiie.Close [folderHandie]; 

}; 

-stick the name of the folder in writer. 
AppendFolderName: procedure [ 

applFolder: NSFiie.Handle, writer: xstring.Writer] s { 

attrs: NSFile.AttributesRecord; 

rb: xstring.ReaderBody; 

NSFile.GetAttributes[applFolder, [interpreted: [name : 
TRUE]],@attrs]; 

rb «-xstring.FromNSString [attrs.name]; 
xstring.AppendReader [writer, @rb]; 
NSFiie.ClearAttributes[@attrs]; 

}; 

This example is somewhat similar to the message file example. 
The basic goal is to obtain the name of the TIP file from the 
application folder. To do this, we call AppendTIPFileName, 
which gets the name of the folder by calling GetAttributes, 
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and then gets the name of the file from the ADF. These two 
names are concatentated into the pathName variable, which is 
then used to create the runtime TIP table. 

If there is no application folder, the default hard-coded value 
of SampleBWSApplication.TIP will be used. You should only 
use hard-coded information during development. 



1 6.2.3 Private icons file 



If you want your application to use an icons file, you need to 
modify your Setlmplementation procedure so that it doesn't 
use a PictureProc. When you use application folders, you don't 
have to worry about finding the icon file; if you register the file 
type that you are interested in, Viewpoint will locate the icon 
file when the user loads the application and associate the 
application and its icon by type. 

Here is an example of a Setlmplementation procedure that 
uses an icon file instead of a PictureProc. Notice that there is no 
mention of the PictureProc or SmallPictureProc. 

samplekonFlielype: NSFile.Type = WOlOO; — arbitrary 

Setlmplementation: procedure s { 

mh: XMessage.Handie ■ Defs.GetMessageHandle[]; 
oldlmpi ^ newlmpi «- 

containee.Getlmplementation[samplelconFiieType]; 
newlmpl.convertProc "(-Containee.DefaultFileConvertProc; 
newlmpl.genericProc <- GenericProc; 
newlmpi. name «- XMessage.Get [ 
mh,SampieBWSAppiicationOps.kApplicationName]; 
[] <-Containee.Setlmplementation [ 

samplelconFileType, newlmpi]; 

}; 



16.3 Create the application folder 



Once you have created all your data files, and modified your 
code so that it uses the data files, you still need to actually 
create the application folder. To do this, you need to: 

• Copy all of the components, including the ADF, into a folder. 

• Run the application folder tool, Applize.bcd. This will put 
two items in the Attention window menu: 

Folder Application 

Application -^-Folder 

The first item takes a regular folder and turns it into an 
application folder. It does this by changing the file type of the 
folder and stamping the create date with the current date and 
time. It also sets the version to OS 6.0. 
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The second item turns an application folder back into a regular 
folder. It changes the file type back to "folder" and sets the 
version to nil. 



Thus, to turn a folder into an application folder, just.select the 
folder, and then invoke Folder Application. Figure 16.2 
illustrates the steps of buildng an application folder. 




Figure 16.2 Building an application folder 



16.4 Summary 



To create an application folder, you need to do the following: 

• Build the data files for the application 

• Write an application description file 

• Change code so that it accesses the data files 

• Integrate the components into an application folder 

The hardest part is writing the code that acceses the data files. 
Starting with the internal name of the folder, you need to do 
the following: 

• Get a reference to the folder with specified internal name. 
(AppllcationFolder.FromName) 

• open the folder 

• Get a reference to the ADF within that folder 
(ApplicationFolder.FlndDescrlptionFlie) 

• Parse the ADF to get the name of your desired data file. 
(OptionFile.GetString Value) 
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16.5 Exercise 



The assignment for this chapter is to turn the Black Book 
application into an application folder. Black Book was the 
exercise for Chapter 13, NSSegment; if you have not done this 
exercise, you will need to go back and read the description in 
Chapter 13. Also, if you do not have a working version of this 
application, then you will need to retrieve our version from the 
solutions for Chapter 13. 

You need to create a messages file, an icon file, and an ADF, 
modify the code to reference the new data files, and then run 
the Applize tool to create an application folder. 
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Notes: 
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This chapter introduces the document interfaces, which are a 
group of interfaces that enable you to create or read the 
contents of Viewpoint documents. The principle interface in 
this group is DoclnterchangeDefs, which supports creating and 
reading basic document structures such as text, fields, 
headings/ footings, frames, and formatting characters. 

Although DoclnterchangeDefs includes the facilities for adding 
frames to documents, it does not include the facilities for 
creating the contents of frames; there are separate interfaces 
for dealing with graphics, tables, and the like. We discuss these 
frame content interfaces in the next chapter. 



17.1 Creating documents 



To create a new Viewpoint document, you call 
DodnterchangeDefs.StartCreation. This creates a document whose 
only contents are a single page format character and a single 
new paragraph character. 

DoclnterchangeDefs.StartCreation: PROC [ 

paginateOption: DocinterchangeOefs.PaginateOption <- 
compress, 

wantHeadingHandles, wantFootingHandles: bool<- false, 
initialFontProps: FontPropsDefs.ReadonlyProps <~nil, 
initialParaProps: ParaPropsDefs-ReadonlyProps <-nil, 
initialPageProps: DocPagePropsDefs.ReadonlyProps <-nil] 

RETURNS [ 

doc: DoclnterchangeDefs.DOC, 
doclzn: InstanceDefs.lzn, 

leftHeading, rightHeading: DocinterchangeOefs.Heading, 
leftFooting, rlghtPooting: DocinterchangeOefs.Footing]; 

DoclnterchangeDefs.PaginateOption: TYPE a { 
none, simple, compress}; 

DoclnterchangeDefs.DOC: TYPE - LONG POINTER TO 
DoclnterchangeDefs.DocObject; 

DoclnterchangeDefs.DocObject: TYPE; 

InstanceDefs.lzn: TYPE ■ RECORD [UNSPECIFIED]; 

paginateOption specifies the type of pagination that will occur 
when you finish the document, compress pagination is full 
pagination, simple pagination provides the same external 
appearance as compress pagination, but leaves the internal 
structure of the document less compact, none leaves the 
document without any pagination at all. If your document will 
be longer than a few pages, you should use some form of 
pagination, or performance will be very slow. 
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wantHeadingHandles and wantFootingHandles specify 
whether the document will have headings and footings. If you 
specify true for either of these parameters, StartCreation will 
return handles to the headings and footings. Like the 
document itself, the headings and footings will be initially 
blank; the next section discusses how to add content to the 
document and its headings. 

InitialFontProps, initiaiParaPros, and initialPageProps indicate 
the initial properties for the document. If you do not specify 
any properties, StartCreation will use the document default 
properties. See Section 17.2 for more information on 
properties. 

StartCreation returns a Doc handle, a doclzn, and handles for 
headings and footings. 

The doclzn is a storage space that holds various "instances" 
(objects) within the document. You can just elide this value. 
The heading and footing handles will be NIL unless you 
specified TRUE for the corresponding want*Handle parameter. 
If you have a valid heading or footing handle, you must later 
free it; see section 17. 1.1. 4 for details. 

The Doc handle represents the new document, which does not 
yet have any contents. Thus, the next step is to pass this handle 
to the Append* procedures described below, which allow you 
to add various kinds of information to the document. 



1 7.1 .1 Adding information to a document 



Once you have a document handle, the next step is to add 
information to the document with various Append* 
procedures: AppendAnchoredFrame, AppendChar, 
AppendColumnBreak, AppendFleld, AppendNewParagraph, 
AppendPageBreak, AppendPFC (Page Format Character), or 
Appendlext. (All of these procedures are in the 
DoclnterchangeDefs interface.) 

Each of these procedures appends the specified text or 
formatting character to the existing text in the document. You 
thus add all desired information to the document sequentially. 
Some of the objects within a document, such as page format 
characters and fields, can themselves have contents. Thus, the 
process of adding information to a document can be recursive. 
Figure 17.1 illustrates the kinds of information that you can 
add to a document. 
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17.1.1.1 Adding text 
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Figure 17.1 : Appending to a document 



The routines that append textual information-AppendChar, 
AppendField, AppendNewParagraph, and AppendText-take a 
DocinterchangeDefs.TextContainer and a piece of data as 
parameters, and append the data to the text container. 

A TextContainer is any object that can contain text: a caption, 
document, field, heading, or footing: 

DoclnterchangeDefs.TextContainer: TYPE a RECORD [ 
var: select type: * from 

caption ■ > [h: DoclnterchangeDefs.Caption], 
doc sa > [h: DoclnterchangeDefs.Doc], 
field a > [h: DoclnterchangeOefs.Field], 
heading ■ > [h: oocinterchangeDefs.Heading], 
footing = > [h: DoclnterchangeOefs.Footing], 
endcase]; 

The individual types are all opaque: for example, here are the 
declarations of caption and doc: 

DoclnterchangeDefs.Caption: TYPE a 

LONG POINTER TO DoclnterchangeDefs.CaptionObject; 

DocinterchangeDef s.CaptionObject: TYPE ; 

DoclnterchangeDefs.Doc: TYPE a 

LONG POINTER TO DoclnterchangeDefs.DocObject; 

DoclnterchangeDefs-DocObject: TYPE; 

Thus, you add information to a header within a document the 
same way that you add information to the document itself: the 
TextContainer that you pass to AppendChar can be a heading, 
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a document, or any of the other variants. Note that you get the 
different types of text containers from different routines: doc, 
heading, and footing come from StartCreation; caption and 
field from AppendAnchoredFrame and AppendField, 
respsectively. See below for more information on these two 
procedures. Figure 17.2 illustrates adding information to a 
header within a document. 




Figure 17.2: Adding text to a header 



Note that all TextContainers always contain at least one 
newParagraph character; you don't have to provide the initial 
paragraph character. Also note that most of the Append 
routines allow you to specify new properties for the 
information you want to append. If you default this 
information, the new information will inherit the properties of 
the preceding paragraph or character, as appropriate. See 
Section 17.2 for a more complete discussion of the various 
properties. 



As an example of one of these procedures, here is the 
declaration of AppendChar: 

DoclnterchangeDefs.AppendChar: PROC [ 
to : Doclntercha ngeOef s.TextCo nta i ne r , 
char: xchar.Character, 

fontProps: FontPropsOefs.ReadoniyProps «-nil, 
nToAppend: CARDINAL <-1]; 

AppendChar appends one or more copies of the text character 
char to the specified TextContainer. nToAppend specifies the 
number of copies of the character that are to be appended; 
fontProps specifies the character properties. AppendText is 
similar, except it takes an xstring.Reader as a parameter instead 
of an xchar.Character. 
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AppendField is slightly different, because it returns a text 
container that you can use in other calls to Append* routines: 

DoclnterchangeDefs-AppendFleld: PROC [ 
to: DoclnterchangeDefs.TextContalner, 
fieldProps: FieidPropsDefs.ReadonlyProps, 
fontProps: FontPropsDefs.ReadonlyProps <-nil] 
RETURNS [field: DoclnterchangeDefs.Field]; 

AppendNewParagraph is straightforward: 

DocinterchangeDefs.AppendNewParagraph: proc [ 
to: DoclnterchangeDefs.TextContainer, 
paraProps: ParaPropsOefs.ReadonlyProps f-NiL]; 

The only part of this that is slightly tricky is the syntax for 
specifying the variant. For example, here is a code fragment to 
create a document and add some text to it: 

doc : DoclnterchangeDefs.DOC <-OoclnterchangeDefs.StartCreation []; 
DoclnterchangeDefs.AppendText[ 

to: [doc[h: Doc]], 

text: @text, 

textEndContext: xstring.unknownContext]; 

AppendText appends an xstring.Reader to the document, 
assuming that the variable text contains some string. This is a 
very incomplete fragment, but it does illustrate how to convert 
a document handle to a doc variant of a TextContainer. 

17.1.1.2 Adding formatting information 



The remaining Append procedures-AppendAnchoredFrame, 
AppendColumnBreak, AppendPageFormatCharacter, and 
AppendPageBreak-take only a Doc, and not a general purpose 
TextContainer. These procedures append characters that can 
appear in a document, but not in other TextContainers such as 
headings and footings. 

AppendColumnBreak, AppendPFC, and AppendPageBreak 

each take a document and some properties as parameters, and 
append the specified character with the specified properties to 
the document. 

Like AppendField, AppendPFC returns a text containere: this 
allows you to call Append* routines recursively to add text and 
formatting information to RFC headers if you like. It will return 
NIL headings and footings unless you specify true for one of the 
want*Handle parameters. 

DoclnterchangeDefs-AppendPFC: PROC[ 
to: DoclnterchangeDefs.DOC, 
pageProps : DocPagePropsoef s. Readon I y Props, 
wantHeadingHandles, wantFootingHandles: bool<- false, 
fontProps: FontPropsDefs.ReadonlyProps <- nil] 

RETURNS [ 

leftHeading, rightHieading: Docinterchangeoefs.Heading, 
leftFooting, rightFooting: DocinterchangeOefs.Footing]; 

AppendPFC appends a page format character to the main 
document text. 
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17.1.1.3 Adding frames 



AppendAnchoredFrame appends an anchored frame such as a 
graphics or bitmap frame to a document. 

DocinterchangeDefs.AppendAnchoredFrame: proc [ 
to: DoclnterchangeOefs.DOC, 
type: DocinterchangeDefs.AnchoredFrameType, 
anchoredFrameProps: DocFramePropsDefs.ReadonlyProps, 
content: instanceoefs.instance <-instanceDefs.instanceNil, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: bool<- false, 
anchorFontProps: FontPropsOef s. Readonly Props nil] 

RETURNS [ 

anchoredFrame: instanceDefs.lnstance, 
topCaption, bottomCaption, 

leftCaption, rightCaption: DocinterchangeDefs.Caption]; 

DoclnterchangeDefs.AnchoredFrameType: TYPE = 
MACHINE DEPENDENT { 

nil(O), bitmap, 

cuspButton, equation, graphics, IMG, table, text, 
firstAvailabie, lastAvailable(255)}; 

AppendAnchoredFrame appends the anchored frame type 
with properties anchoredFrameProps to the document to. 
content is a pointer to the contents of the frame. 
DoclnterchangeDefs does not provide the facilities for creating 
the contents of frames; instead, you will have to use 
specialized interfaces such as GraphicslnterchangeDefs or 
TablelnterchangeDefs to create the contents of the frame, and 
then call AppendAnchoredFrame to add that frame and its 
contents to the document. See the next chapter for details; for 
now, just assume that you have a pointer to the contents of the 
frame. 

The want*CaptionHandle parameters indicate whether you 
want the frame to have captions. If you indicate true for any of 
these parameters, the procedure will return a valid caption 
handle, which you can then use as a text container in other calls 
to Append routines. If you specify true, and receive a valid 
caption handle, you must later free the storage for that handle, 
as described in the next section. 

17.1.1.4 Storage management 



With all of the Append procedures, you must manage the 
storage for the property records or other data structures that 
you pass in, except for handles obtained from the interface 
itself. The storage for the properties must remain valid during 
the call to Append*; after Append* returns, you can free it. 

Also, you are responsible for freeing any non-NIL handles 
obtained from any Append routines, or from StartCreation. 
with a call to an appropriate Release* routine. This applies to 
caption handles, field handles, and heading/footings. Here are 
the declarations of the relevant Release routines: 
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DoclnterchangeDefs.ReleaseCaption: PROC [ 

captionPtr: long pointer to DoclnterchangeDefs.Caption]; 

OoclnterchangeDefs.ReleaseField: PROC [ 

fieldPtr: long pointer to DoclnterchangeDefs.Field]; 

DoclnterchangeDefs.ReieaseHeading: PROC [ 

headingPtr: long pointer to DocinterchangeDefs.Heading]; 

DoclnterchangeDefs-ReleaseFooting: PROC [ 

foOtingPtr: long pointer to DoclnterchangeDefs.FOOting]; 

After you call Release*, the handle will be invalid. To help 
prevent use of an invalid handle, the Release* routines take a 
pointer to the handle, and set the handle itself to nil. (This is 
similar to Mesa's free operation.) 



17.1.2 Finalizing document 



When you have added all the necessary information to a 
document, you must call DodnterchangeDefs.FinishCreation to 
finalize the document and release the Doc handle. 
FinishCreatlon returns an NSFiie.Handle to the newly-created 
document, and a status. The document that FinishCreatlon 
provides will be in paginated form if you so specified in 
StartCreation. 

DoclnterchangeDefs-FlnishCreatlon: PROC [ 

docPtr: long pointer to DoclnterchangeOefs.Doc] 
RETURNS [ 

docFlle: NSFiie.Handle, 

status: DocinterchangeDefs.FinishCreationStatus]; 

DocinterchangeDefs.FinishCreationStatus: type ■ {ok, 
okButNotEnoughDiskSpaceloPaginate, 
okBuNotEnoughVMToPaginate, 
okButUnknownPaginateProblem, unknownProblem}; 

This document file is temporary, and will be deleted when you 
reboot. To make the file permanent, you must move it to the 
current user desktop with NSFiie.Move, followed by a call to 
starDesktop.AddReference to put the icon on the display. To do 
this, you must first get a reference to the file and to the current 
desktop. Here is a fragment to illustrate this; there is a 
complete example at the end of this section: 

doc File: NSFiie.Handle <-DocinterchangeDefs.FinishCreation[...]; 
-get reference to file 

refDoc: NSFiie.Reference <-NSFiie.GetReference[docFile]; 
--get reference to desktop 

refDT: NSFiie.Reference <-starDesktop.GetCurrentDesktopFile[]; 
—open file 

fileDT: NSFiie.Handle <-NSFiie.OpenByReference[refDT]; 

-move file to desktop 

NSFiie.Move[docFile, fileDT]; 

NSFiie.Close[fileDT]; 

NSFiie.Close[docFile]; 

starDesktop.AddReferenceToDesktop[refDoc]; 
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If you want the opportunity to abort creation under certain 
circumstatnces, you can use FinishCreationWithAbortProc 
instead of FinishCreation: 

DocinterchangeDefs.FinishCreationWithCheckAbortProc: proc [ 
docPtr: long pointer to DoclnterchangeDefs.Doc, 
checkAbortProc: DocumentDefs.CheckAbortProc, 
ciientData: long pointers- nil] 

RETURNS [ 

docFile: NSFiie.Handle, 

status: DocinterchangeDefs.FinishCreationStatus, 
aborted: boolean]; 

DocumentDefs.CheckAbortProc: PROC [ciientData: long pointer] 
RETURNS [abort: boolean]; 

FinishCreationWithCheckAbortProc provides the ability to 
abort the document creation. DoclnterchangeDefs will call you 
checkAbortProc just before it creates the document; if it 
returns true, the process will be aborted. At that point, you 
should call AbortCreation. 

DocinterchangeDefs-AbortCreation: PROc[docPtr: long pointer to 
DoclnterchangeDefs.Doc] ; 

AbortCreation aborts document creation and deallocates the 
storage associated with that document. 



17.2 Properties 



Each of the objects in a document has associated properties; 
there is a separate interface for each of these possible types of 
properties. DocFramePropsDefs describes the properties of an 
anchored frame within a document; DocPageProps describes 
the properties of a page format character, ParaPropsDefs 
describes paragraph properties, FieldPropsDefs describes a 
field, and FontPropsDefs describes font properties. 

Each of these interfaces contains the following three types: 

Props: TYPE ■ LONG POINTER TO PropsRecord; 

ReadonlyProps: type ■ long pointer to readonly PropsRecord; 

PropsRecord: TYPE a record [ 
. . .]; 

The PropsRecord contains various fields for the particular 
properties. We include the declarations each of the 
PropsRecords here, but not all of the subsidiary types that they 
reference, since that would take up too much space. To see the 
full declarations, consult the appropriate chapter of the 
Viewpoint Programmer's Manual. 
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17.2.1 Anchored frame properties 



DocFramePropsPropsRecord: TYPE a RECORD [ 
borderStyle: BorderStyle ^ trash, 
borderThickness: cardinal*- trash, 
frameDims: DocFrameProps.FrameDims <- trash, 
f ixedWidth, f ixedHeight: bool <- trash, 
span: Span «- trash, 

verticalAlignment: DocFrameProps.VerticalAlignment <- trash, 
horizontalAlignment: DocFrameProps.HorizontalAlignment 
<- trash, 

topMarginHeight, bottomMarginHeight, 
leftMarginWidth, rightMarginWidth: cardinal <~ trash]; 



17.2.2 Font properties 



FontPropsDefs.PropsRecord: type a machine dependent record [ 
f ontDesc(0 :0..31 ) : FontPropsDef s.FontDescri ption, 
offset(2:0..15): integers- trash, 
foregroundBackground(3:0..1): 

FontPropsDefs.ForegroundBackground, 
nUnderlines(3:2..3): cardinal[0..3] ^trash, 
strikeout(3:4..4): boolean <- trash; 
placement(3:5..7): FontPropsDefs.Placement <- trash, 
unused3(3:8..15): packed array [8.. 15] of [0..1] «-all[0]]; 



17.2.3 Page properties 



DocPagePropsDefsPrOpsRecOrd: type = machine dependent RECORD [ 

pageDims(0:0..31): DocPagePropsDefsPageDims ^trash, 
topMarginHeight(2:0..1 5): cardinal <- trash, 
bottomMarginHeight(3:0..1 5): cardinal <- trash, 
leftMarginWidth(4:0..15): cardinal trash, 
rightMarginWidth(5:0..1 5): cardinal <- trash, 
startingPageSide(6:0..1): DocPagePropsDefsPageSide <- trash, 
bindingMarginWidth(6:2..15): cardinal[0.. 16383] <- trash, 
nColumns(7:0..6): cardinal[1..127] <- trash, 
balancedColumns(7:7..7): bool trash, 
unused7(7:8..15): packed array [8.. 15] of [0..1] <-all[01, 
columnSpacing(8:0..15): cardinal trash, 
startingPageNumber(9:0..15): cardinal trash, 
pageNumberFormat(10:0..2): 

DocPagePropsDefs-NumberFormat <- trash, 
restartPageNumbering(10:3..3): bool <- trash, 
unused10(10:4..15): packed array [4.. 15] of[0..1] «-all[0], 
startingLineNumber(1 1 :0..1 5): cardinal <- trash, 
lineNumberlnterval(12:0..10): cardinal[0..2047] <- trash, 
lineNumberFormat(1 2:1 1 ..1 3): NumberFormat trash, 
lineNumberLocation(12:14..15): 

DocPagePropsDefs.LineNumberLocation ^ trash, 
headihgStartsOnThisPage(13:0..0): bool <- trash, 
headingSameOnLeftRightPages(1 3 : 1 ..1 ) : bool ^ trash, 
fQOtingStartsOnThisPage(13:2..2): bool ♦-trash, 
foQtingSameOnLeftRightPages(13:3..3): bool <- trash, 
unused13(13:4..15): packed array [4.. 15] of [0..1] e-ALL[0]]; 
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17.2.4 Field properties 



FieldPropsDefs.PropsRecOrd: TYPE = RECORD [ 

language: MuitiNationai. Language ^trash, 

length: cardinal <- trash, 

required: boolean <- trash, 

skiplf : FieidPropsDefs.SkiplfChoiceType 4- trash, 

stopOnSkip: boolean <- trash, 

type: FieldPropsDefs.FleldChoiceType trash, 

filllnRule, 

description, 

format, 

name, 

range, 

skiplf Field: xstring.ReaderBody <- trash, 
filllnRuleRuns: FontRunDefs.FontRuns <- trash]; 



1 7.2.5 Utilities for getting and setting properties 



DoclnterchangeDefs also provides some routines to get and set 
properties easily. The following three routines create 
properties records with "reasonable" default values: 

DoclnterchangeDefs.GetFontPropsDefaults: PROC [ 
props: FontPropsDefs.Props]; 

DoclnterchangeDefs.GetPagePropsDefaults: PROC [ 
props: DocPagePropsDefs.Props]; 

DoclnterchangeDefs.GetParaPropsDefaults: PROC [ 
props: ParaPropsDefs.Props]; 

To set properties, you can use SetCurrentPa rag raph Props: 

DocinterchangeDefs-SetCurrentParagraphProps: proc [ 
textConta i ner : oocinterchangeDef s.TextConta i ne r, 
paraProps: ParaPropsOefs.ReadonlyProps]; 

You can call SetCurrentParagraphProps at any time, with any 
TextContainer as an argument. If you call it repeatedly, only 
the most recent call will remain in effect. 

SetCurrentParagraphProps affects the entire current 
paragraph, including any text that you append later. The 
properties also affect all subsequent paragraphs unless you 
override the properties with new ones passed to 
AppendNewParagraph, or by another call to 
SetCurrentParagraphProps. 

Note, however, that you must be careful when calling 
SetCurrentParagraphProps on an empty text container. The 
algorithm that DoclnterchangeDefs uses for adding the initial 
new paragraph properties is to check before doing an 
Append*, and add a paragraph character if there is not already 
one there. Thus, calling SetCurrentParagraphProps before 
calling any Append* routines will result in an error, since there 
is not yet a paragraph character in the text container. 
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17.3 Example 



Here is a simple example that creates a new document and puts 
a few words in it. Note that it is just a command procedure, and 
not a complete example: 

-called when user invokes some command 
MakeDoc: MenuData.MenuProc a { 

doc: DoclnterchangeDefs.DOC <— nil; 

heading: DocinterchangeOefs.Heading <-nil; 

fontProps: FontPropsDefs.PropsRecord; 

pageProps: DocPagePropsDefs.PropsRecord; 

pa ra Pr o ps : Pa ra PropsDef s . P r o ps Reco rd ; 

status: DocinterchangeDefs.FlnishCreationStatus; 

docFile: NSFiie.Handle; 

-strings for doc. and header contents. 

text: xstrlng.ReaderBody <-xstrlng.FromSTRING[ 
"But if the while I think on thee, dear friend. 
All losses are restored and sorrows end."L]; 

headerText: xstring.ReaderBody ^xstring.FromSTRING[ 
"Shakespeare"L]; 

-get default properties 

DocinterchangeDefs.GetFontPropsDefaults[@fontProps]; 

DocinterchangeDefs.GetParaPropsDefaults[@paraProps]; 

DocinterchangeDefs.GetPagePropsDefaults[@pageProps]; 

-create new document with headings and no footings. 

-elide docizn, footing, and second heading, since left 

-and right headings will be the same 

[doc, , heading, , ] <-DocinterchangeDefs.StartCreation[ 

paginateOption: compress, 

wantHeadingHandles: true, 

wantFootingHandles: false, 

initialFontProps: ©fontProps, 

initialParaProps: @paraProps, 

initialPageProps: @pageProps]; 
-add text to document and header 
DoclnterchangeDefs.AppendText[ 

to: [doc[h: doc]], 

text: @text, 

textEndContext: xstrlng.unknownContext]; 
DocinterchangeDefs.AppendText[ 
to: [heading[h:leftHeading]], 
text: headerText, 

textEndContext: xstring.unknownContext]; 
--free header and then finish up 
DocinterchangeDefs.ReleaseHeading[@heading]; 
[docFile, status] <-DocinterchangeDefs.FinishCreation[@doc]; 
IF status # ok THEN UserTermina[.BlinkDisplay[] 
ELSE { -copy document to desktop 

refDoc: NSFiie.Reference <-NSFiie.GetReference[docFile]; 

refDT: NSFiie.Reference <- 

starDesktop.GetCurrentDesktopFile[]; 

fileDT: NSFiie.Handle <-NSFile.OpenByReference[refDT]; 

NSFiie.Move[docFile, fileDT]; 

NSFiie.Close[fileDT]; 

NSFiie.CloseidocFiie]; 

starDesktop.AddReferenceToDesktop[refDoc]; 

}; 
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1 7.4 Enumerating documents 



To read (Enumerate) the contents of an existing Viewpoint 
document, the first step is to call Open, which opens the 
document and returns a Doc handle for that document. 

DodnterchangeDefs.Open: PROC[ 
docFlleRef: NSFiie. Reference, 
password: xstring.Reader <- nil] 

RETURNS [ 

doc: DoclnterchangeDefs.DOC, 

Status: DoclnterchangeDefs.OpenStatUS]; 

DoclnterchangeDefs.OpenStatus: TYPE ■ { 
ok, badSeal, cantOpenlzn, incompatible, 
notLocal,outOfDiskSpaceForBackup, 
outOfDlskSpaceToUpgrade, outOfVMToUpgrade, 
unknownProblem, outOfVMToOpen, accessConf Met, 
invalidPassword}; 

password is currently ignored. 

Once you have a handle to the document, the next step is to 
call Enumerate, passing in the Doc and an EnumProcs record. 
The EnumProcs record contains a set of callback procedures, 
one for each of the following structures: {anchored frame, 
column break, field, new paragraph, page break, page format 
character, text, tile}. 

DoclnterchangeDefs.Enumerate: PROC [ 

textContainer: DocinterchangeDefs.TextContainer, 
procs : Doclntercha ngeDef s. En U m PrOCS, 

clientData: long pointers- nil] 
RETURNS [dataSkipped: bool]; 

DoclnterchangeDefs.EnumProcs: TYPE a LONG POINTER TO 
Doclntercha ngeOef s. E n u m ProcsRecord ; 

DocinterchangeDefs.EnumProcsRecord: TYPE a record [ 
anchoredFrameProc: 

DocinterchangeDefs.AnchoredFrameProc ^ NIL, 
columnBreakProc: DocinterchangeDefs.ColumnBreakProc «-nil, 
fieldProc: DoclnterchangeDefs.FleldProc <— nil, 
newParagraphProc: 

DoclnterchangeDefs.NewParagraphProc ^ NIL, 
pageBreakProc: Docinterchangeoefs.PageBreakProc ^t-NiL, 
pfcProc: DoclnterchangeDefs.PFCPrOC ^ NIL, 
textPrOC: DoclnterchangeDefs.TextProc «- nil, 
tlleProc: DodnterchangeDefs.TileProc<-NIL]; 

Enumerate proceeds sequentially from the beginning of the 
document: as it comes to different structures within the 
document, it calls the appropriate callback procedures (which 
you have to write.) If you don't supply a procedure for some 
type of object. Enumerate will ignore all objects of that type. 

Each of the call back procedures takes as parameters the 
properties of the structure and its content when appropriate. 
For example, here are the declarations of two of the 
procedures, one with content and one without. Since the 
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Others are quite similar, we won't include all the declarations; 
see the Viewpoint Programmer's Manual for a complete list. 

DoclnterchangeDefs.ColumnBreakProc: TYPE » proc[ 
clientData: long pointer, 
f ontProps : FontPropsOef s. Readon I y Props] 

RETURNS [stop: BOOL «- FALSE]; 
DoclnterchangeDefs.TextProc: TYPE = PROC [ 

clientData: LONG POINTER, 
fontProps: FontPropsDefs.ReadonlyProps, 
text: xstring.Reader, 
textEndContext: xstring. Context] 

RETURNS [stop: BOOL <- FALSE]; 

clientData is the clientData that you passed to Enumerate. 

The data handle (header, caption, etc.) supplied to you in the 
call-back is readonly and is valid only during the call-back's 
invocation; you should not try to free this handle. It is possible 
for such a handle to be nil; a nil handle means that the 
corresponding object has no text content. 

The storage for the properties passed to these procedures is 
also temporary; you must explicitly copy any properties that 
you want to save. 

Each of the call back procedures returns a boolean value stop; 
if any one of the procedures returns stop = true, the 
enumeration will terminate. If stop is never true, the 
enumeration will continue to the end of the document. 

Note that the enumeration does include the default paragraph 
and page format characters supplied with the TextContainer. 
Thus, when copying a document into a new document, you 
should be careful to avoid copying the default paragraph and 
page format properties, since that would cause duplication. 

Document enumeration can be recursive, just like document 
creation. For example, if there is a page format character in the 
document, then you can use Enumerate recursively to parse the 
contents of that page format character. 

When the enumeration is complete, you should call Close to 
free all associated data structures and close any open file 
handles to the document. Close sets docPtr| to nil 

DoclnterchangeDefs.Close: PROC[ 

docPtr: long pointer to DoclnterchangeOefs.Doc]; 
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17.5 Summary 



Creating a new document requires the following steps: 

• Call DocinterchangeDefs.StartCreation to get a doc handle 

• Pass that doc handle to DocinterchangeDefs.Append* to add 
information to the document 

• Call oocinterchangeDefs.Release* to release any valid 
caption, heading, footing, or field handles. 

• Call DocinterchangeDefs.FinishCreation to complete the 
document 

• Call NSFiie.Move to move the file to the desktop and 
make it permanent and then starOesktop Add Reference to 
display the new icon on the desktop. 

Enumerating a document involves the following steps: 

• Call DocinterchangeDefs.Opento get a document handle 

• Call DocinterchangeDefs.Enumerate, passing in the document 
handle and a record of call back procedures to enumerate 
the vaious items within the document 

• Call DocinterchangeDefs.Ciose to close the document. 



1 7.6 Example: copying a file 



Here is an example of both enuemration and creation. This 
program adds the command DocEx to the Attention Window. 
When called, this command checks to see if the current 
selection is a document. If it is, then the program enumerates 
the contents of that document and copies the information into 
a new document. 

< < A DICtxtHandle is passed as clientData to procs called by 
DocinterchangeDefs.Enumerate. The record contains handles 
to the new document, 3nd the old document. ignoreNewPar 
and ignorePFC allow you to avoid duplicating the initial page 
format character and initial new paragraph character. > > 
DICtxtHandle: TYPE - long pointer to DICtxt; 
DICtxt: type ■ record [ 

SOurceDoc, targetDoc: DoclnterchangeOefs.Doc, 

IgnoreNewPar, IgnorePFC: boolean]; 

TabStopsHandle: TYPE a long pointer to TabStops; 
TabStops: TYPE a record [ 

list: SEQUENCE length: cardinal of ParaPropsOefs.TabStOp]; 

z: UNCOUNTED ZONE a Heap.systemZone; 
dIEnumProcs: DocinterchangeDefs.EnumProcs <-nil; 



17-14 



VIEWPOINT programming COURSE 



DOCINTERCHANGE 



< < This is tlie command procedure. It copies the contents of 
the currently selected document to a new document. > > 
MakeDoc: MenuData.MenuProc ■ { 
-get reference to selected file 
IF seiection.CanYouConvert[f ile] then { 

selValue: Seiection.Value <-Seiection.Convert[file]; 
docFileRef : NSFiie. Reference ■ loophole[ 

selValue.vaiue, long pointer to NSFiie.Reference] | ; 

"Open source document 
SOurceDoc: DoclnterchangeDefs.Doc; 
OpenStatus: DoclnterchangeDefs.OpenStatus; 
[sourceDoc, openStatus] <- 

DoclnterchangeDef s.Open [docFi leRef ] ; 

IF openStatus - ok then { 
-declare some variables 
ta rgetDoc : DoclnterchangeDef s. Doc; 
diCtxt: DICtxt; 
docFile: NSFiie. Handle; 
ref Doc, ref Dt: NSFiie.Reference; 
fileDt: NSFiie.Handle; 
tabStops: TabStopsHandle; 
fontProps: FontPropsDefs.PropsRecord; 
pa ra Props : Pa ra PropsOefs. Props Reco rd ; 
pageProps : DocPagePropsoef s.PropsRecord ; 
-get props from source document, and create new doc 
-with those props 
GetlnitialDocProps[ 

docFileRef, ©sourceDoc, @fontProps, @paraProps, 

@pageProps, @tabStops]; 
paraProps.tabStops f- 

iF tabStops ■ nilthendescriptor[NIL,0] 

ELSE DESCRiPTOR[@tabStops.list[0], tabStops.length]; 
targetDoc <- DocinterchangeDefs.StartCreation[ 

paginateOption: simple, initialFontProps: @fontProps, 

initialParaProps: ©paraProps, 

initialPageProps: ©pageProps]. doc; 
IF tabStops # NIL then z.FREE[©tabStops]; 
diCtxt <<- [sourceDoc, targetDoc, true, true]; 

"Start enumeration 

[] DoclnterchangeDefs.Enumerate[ 

[doc[h: sourceDoc]], diEnumProcs, ©diCtxt]; 
-enumeration done. Close source doc; create new doc, 
make it permament, and display it on desktop. 
DoclnterchangeDefs.Close[@SOurceDoc]; 
docFile <- DoclnterchangeDef s.FinishCreation[ 

©targetDoc].docFile; 
refDoc<-NSFiie.GetReference[docFile]; 
refDt «-starDesktop.GetCurrentDesktopFile[]; 
fileDt «-NSFiie.OpenByReference[refDt]; 
NSFiie.Move[docFile, fileDt]; -- put new doc on Desktop 
NSFiie.CloselfileDt]; 
NSFiie.Ciose[docFile]; 

starDesktop.AddReferenceToDesktop[refDoc]; 
} 

ELSEUserTerminal.BlinkDisplay[]; 
} 

ELSE UserTerminal.BlinkDisplay[]; 
}; -- MakeDoc 
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< < The call back procedures for enumeration. They all just 
add the specified structure to the new document. > > 

< <Add new paragraph to new document. If it is the first new 
paragraph character, then ignore it, since new document will 
already have one. > > 
AppendNewParToTargetDoc: 

DocinterchangeDefs.NewParagraphProc ■ { 
diCtxt: DICtxtHandle = clientData; 
IF diCtxt.ignoreNewPar then diCtxt.ignoreNewPar <- false 
ELSE DocinterchangeDefs.AppendNewParagraph[ 

[doc[h: diCtxt.targetDoc]], paraProps,fontProps]; }; 

"Append page break to new document 
AppendPageBreakToTargetDoc: 

DoclnterchangeDefs.PageBreakProC a { 
diCtxt: DICtxtHandle ■ clientData; 
DoclnterchangeOefs.AppendPageBreak[ 
dlCtxt.targetDoc,fontProps]; }; 

< <Add page format character to new document If it is the 
first format character, then ignore it, since new document will 
already have one. > > 

AddPFCToTargetDoc: DoclnterchangeDefs.PFCProc = { 

diCtxt: DICtxtHandle > clientData; 

iFdiCtxt.ignorePFC THENdiCtxt.ignorePFC false 

ELSE [] <~OoclnterchangeDef$.AppendPFC[ 

to: diCtxt.targetDoc, pageProps: pageProps, 
fontProps: fontProps]; }; 

-Append text to new document 

AppendTextToTargetDoc: DocinterchangeDefs.TextProc = { 
diCtxt: DICtxtHandle » clientData; 
DoclnterchangeDefs.AppendText[ 

[doc[h: diCtxt.targetDoc!], 

text, 

textEndContext, 
fontProps]; }; 

-Copy the font, para, and page props of source document 
GetlnitialDocProps: proc[. ..]■{...}; 

< < Allocate enumProcs record, and add command to 
attention menu. EnumProcs record is only interested in new 
paragraphs, page breaks, page format characters, and text; it 
ignores all other structures. > > 

Init: PROC = { 

name: xstring.ReaderBody ^xstring.FromSTRING["DocEx"L]; 
diEnumProcs ^ z.new[ 

DoclnterchangeDefs.EnumProcsRecord [ 

anchoredFrameProc: nil, 

columnBreakProc: nil, 

fieldProc: nil, 

newParagraphProc: AppendNewParToTargetDoc, 
pageBreakProc: AppendPageBreakToTargetDoc, 
pfcProc: AppendPFCToTargetDoc, 
textProc: AppendTextToTargetDoc]]; 
Attention. AddMenultem[ 

MenuData.Createltem[z, @name, MakeDoc]]; }; 

init[]; 



17-16 



VIEWPOINT PROGRAMMING COURSE 



DOCINTERCHANGE 



17.7 Exercise 



The Form letter application takes a template document and 
name file as arguments and produces form letters. The 
template has VP fields that contain keywords; when the 
application finds one of these keywords, it substitutes the 
corresponding information from the data file. For example, if 
a field in the template contained the keyword "LAST" then the 
resulting document might contain the name "Smith" from the 
data file. Figure 17.3 illustrates a data file and Figure 17.4 
illustrates a template. 





IQNameFile ^^^ui=i 




Rusty E. Scupper 




333 Oakmead Parkway 


1 


Sunnyvale^ California 94040 




B 


ill Melater 




999 Hog5 Way 




ConVille, Texas 53543 








+ 






t 







Figure 17.3: Data file 



.w■^^vAv^Jj■^^w■WJ»OTX^^^!fp: ^ : v■ o ■■V■T WXWA^w■v.wJ■M^ ^ ^ 



QTemplate^^^^^^^B Close | Save | Reset | Save&Edit | D | □ | S 



5ft 



iFFIRSTjriASTj 

TADDRESSJ 

rCITYjrSTATEjrZIPj 

Dear Mrs. FLASTJ: 

This letter is to inform you that you have rnay have already won 
1. 000^000^000 dollars. Wouldn't vou love to spend all that money in TCITYJ? 
Maybe you could even buy Mr^^^fLASTj a new fur coat. Life in rs"T ATE J sure 
would be areatwith all that 



i^ld cash. 



Sincerely^ 



Mark Hahn 



Figure 17.4: Template document 

To use the program, you select a template file and a data file 
and drop them onto the Form letter maker icon, shown in 
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Figure 17.5. The program will parse the name file, merge its 
information with the template file, and create a new 
document on the desktop for each person in the name file. 




Figure 17.5: Form 
letter icon 

Your assignment is to write the code to merge the template 
with the information in the name file and generate new 
documents. You will need the following files to complete this 
assignment: 



FormLetter.config, 

FormLetterDefs.mesa, 

Form Letterlmpl. mesa. 

Form LetterMsg I m pi . mesa. 

Form LetterDoclmplTemplate. mesa. 



The procedures that you need to implement are all in 
Form LetterDoclmplTemplate. 



17-18 



VIEWPOINT PROGRAMMING COURSE 



18 



GRAPHICS 



This chapter describes how to create and enumerate graphics 
within graphics frames, using the facilities of the 
GraphicslnterchangeDefs interface. GraphicslnterchangeDefs 
is meant to be used in conjunction with DoclnterchangeDefs; 
you need to be familiar with the material in the previous 
chapter before you read this chapter. 

There are also similar interfaces for manipulating tables and 
charts, which we do not discuss in this course. For information 
on creating and reading tables within documents, see the 
TablelnterchangeDefs chapter in the ViewPoint Programmer's 
Manual. For information on creating and enumerating charts, 
see the ChartDatalnstallDefs chapter in the ViewPoint 
Programmer's Manual. 



18.1 Creating graphics 



To create new graphics, the first step is to call StartGraphics, 
which creates a new graphics frame and returns a graphics 
Handle for it. 

Once you have a Handle, you can pass that Handle to various 
Add* routines to add new graphics objects, such as curves, 
rectangles, bitmaps, and text frames, to the graphics frame. 

When you are through adding graphics, the final step Is to call 
FinishGraphics, which returns an object of type 
instanceDefs-lnstance. Typically, you will then pass that handle to 
DocinterchangeDefs.AppendAnchoredFrame to add the frame and 
its contents to a document. 

The following sections discuss each of these steps in detail. 



18.1.1 Start routines 



To create new graphics objects, you must first call 
GraphicsinterchangeDefs.StartGraphics to get an anchored frame 
handle: 

GraphicslnterchangeDefs.StartGraphics: PROC [ 
doc: DoclnterchangeDefs.DOC] 
RETURNS [h: GraphicslnterchangeDefs.Handle]; 

GraphicslnterchangeDefs.Handle: TYPE h 

LONG POINTER TO GraphicslnterchangeDefs.Object; 

GraphicslnterchangeDefs.Object: TYPE; 
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StartGraphics creates a new graphics frame, taking the storage 
from doc. StartGraphics returns a Handle, which is a pointer to 
an opaque type that contains, among other things, a graphics 
container. A graphics container is just an object that can 
contain graphic objects: a graphics container can be an 
anchored graphics frame, a nested graphics frame, a cusp 
button within a graphics frame, or another similar construct, 
such as a chart. 

There are also similar routines to create nested frames within 
an anchored frame: StartGraphicsFrame initializes a nested 
frame within an anchored frame; StartCluster initializes a 
cluster of graphic objects within a graphics frame: 

GraphicslnterchangeDefs.StartCiuster: PROC [ 
h : GraphicsinterchangeOefs.Handie, 
box: GraphicslnterchangeDefs.Box] 
RETURNS [ch: GraphicslnterchangeDefs.Handle]; 

GraphicslnterchangeDefs.Box: TYPE = RECORD [ 
place: GraphkslnterchangeDefs.Place, 
dims: GraphicsinterchangeDef s.Dl ms] ,' 

GraphkslnterchangeDefs.Place: TYPE a RECORD [x, y: INTEGER]; 

GraphkslnterchangeDefs.Dims: TYPE a RECORD [w, h: INTEGER]; 

StartCluster initializes a cluster of graphics objects within the 
graphics frame h. box describes the size and location of the 
cluster relative to the anchored frame; place and dims are in 
micas. (2540 micas = 1 inch.) 

GraphkslnterchangeDefs.StartGraphicsFrame: PROC [ 
h : GraphksinterchangeDefs.Handle, 
box: GraphkslnterchangeDefs.Box, 
frameProps: GraphkslnterchangeDefs.FrameProps, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean <- false] 

RETURNS [ 

gfh: Handle, topCaption, bottomCaption, 
leftCaption, rightCaption: DocinterchangeDefs.Caption]; 

StartGraphicsFrame creates a new nested nonanchored frame 
within the anchored frame h. Again, box describes the location 
of the nested frame. 

want*CaptionHandle indicates whether you want the frame to 
have the corresponding captions. If you pass in true for any of 
these values, StartGraphicsFrame will return a valid caption 
handle; you can then use DoclnterchangeDefs routines to add 
text to the caption. If you pass in true, and receive a caption 
handle, you must eventually free that caption with 
DocinterchangeDefs.ReleaseCaption. See Section 17.1.1.4 for more 
details. 

frameProps are the properties for the nested frame. Note that 
StartGraphics does not have a corresponding parameter to 
specify the properties for the anchored frame; you set these 
properties when you add the frame to a document. See Section 
17.1.1.3 for details. 
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GraphicslnterchangeDefs.FrameProps: TYPE ■ 

LONG POINTER TO GraphicslnterchangeDefs.FramePropsRec; 

GraphicslnterchangeDefs.FramePropsRec: TYPE ■ RECORD [ 
brush : GraphicslnterchangeDef s.Brush, 
expandRight, expandBottom: boolean, 
margins: array GraphkslnterchangeOefs.Side OF CARDINAL, 
captionContent: array Side OFDocinterchangeDefs.Caption 
]; 

GraphicslnterchangeDefs.Brush: TYPE a RECORD [ 
wthbrush: cardinal, 

Stylebrush: GraphicslnterchangeDefs.StyleBrush]; 

GraphicslnterchangeDefs.StyleBrush: TYPE » MACHINE DEPENDENT { 
invisibie(O), solid(1), dashed(2), dotted(3), double(4), 
brol<en(5),(15)}; 

GraphicslnterchangeDef s.Side: TYPE a {top, bottom, left, right}; 

brush describes the properties of the lines that make up the 
frame. The brush width is in micas. The standard brush widths 
on the property sheet are roughly multiples of 35: 35, 71, 106, 
141, 176, and 212. You should use one of these widths. 

expandRight, expandBottom indicate whether the frame 
should expand automatically when the user puts in more 
information; these correspond to the entries on the property 
sheet. 

margins are the frame margins, in points. 

captionContent is an array of captions for the frame. Note that 
this parameter is only interesting during enumeration, since 
you add the caption content after you create the frame. 

Here is a code fragment that creates the graphics frames shown 
in Figure 18.1 : 



Figure 18.1 : Graphics frames 
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doc: DoclnterchangeDefs.DOC <- nil; 
graphics: instanceoefs.lnstance; 

anchoredFrame, nestedFrame: GraphksinterchangeOefs.Handle; 
bCaption: DodnterchangeDefs.Caption; -for bottom caption 
content: xstring.ReaderBody <- 

xstring.FromSTRING["Figure 18.1 : Graphics frames"L]; 
-set up properties for both frames and para props for caption 
nestedProps: GraphkslnterchangeDefs.FramePropsRec <- [ 

brush: [wthbrush: 106,stylebrush: double], 

expandRight: false, expandBottom: false, 

margins: [0,0,0,0], 

captionContent: [nil, nil, nil, nil]]; 
anchoredProps: oocFramePropsDefs.PropsRecord <- [ 

borderStyle: solid, 

borderThickness: 2, 

frameDims: [w: 176, h: 101], 

fixedWidth:TRUE, 

fixedHeight: true, 

span: fullColumn, 

verticalAlignment: floating, 

horizontalAlignment: right, 

topMarginHeight: 0, 

bottomMarginHeight: 0, 

leftMarginWidth: 0, 

rightMarginWidth: 100]; -points; 72 points to the inch 
ca ptionProps : ParaPropsOef s.PropsRecord ; 
DocinterchangeDefs.GetParaPropsDefaults[@captionProps]; 
captionProps.basicProps.preLeading <-10; -points 
captionProps.basicProps.paraAlignment <- center; 

-create doc, then anchored frame, then nested frame, box 
-dimensions are in micas; 2450 micas to an inch 
[doc, , , , ] «-DoclnterchangeDefs.StartCreation[]; 
anchoredFrame «-GraphicsinterchangeDefs.StartGraphics[doc]; 
[nestedFrame, , , ] <-GraphicsinterchangeDefs.StartGraphicsFrame[ 
h: anchoredFrame, 

box: [place: [x: 2540, y: 1270], dims: [w: 2540, h: 1270]], 

frameProps: ©nestedProps]; 
-now finish nested frame and anchored frame, and pass 
-content of anchored frame to AppendFrame 
GraphicsinterchangeDefs.FinishGraphicsFrame[nestedFrame]; 
graphics <— GraphicslnterchangeDefs.FinishGraphics[ 

anchoredFrame]; 
[, , bCaption, ,] <-DocinterchangeDefs.AppendAnchoredFrame[ 

to: doc, 

type: graphics, 

anchoredFrameProps: ©anchoredProps, 

content: graphics, 

wantBottomCaptionHandie: true]; 
-add new par. with new props. Just changing props won't 
-work, because there is not yet a para, char in the caption. 
DocinterchangeOefs. Append Ne wPa rag ra ph [ 

to: caption :[h: bCaption]], 

paraProps: ©captionProps]; 
DoclnterchangeDefs.AppendText[ 

to: [caption[h: bCaption]], 

text: ©content, 

textEndContext: xstring.unknownContext, 

fontProps: ©fontProps]; 
DocinterchangeOefs.ReleaseCaption[©bCaption]; 
-finish document 

[docFile] <— DoclnterchangeDefs.FinishCreation[@doc]; 
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18.1.2 Add routines 



After calling a Start* routine to initialize a graphics container, 
the next step is typically to call various Add* routines to add 
information to the graphics container. The Add* routines all 
add a specified object to a specified place in the graphics 
frame. 

Note that we have not included the declarations of all possible 
graphics routines; for a complete list, check the 
GraphicslnterchangeDefs documentation in the ViewPoint 
Programmer's Mar)ual. 

18.1.2.1 Lines 



AddLlne is a basic example of an Add routine: 

GraphicslnterchangeDefs.AddLlne: PROC [ 
h: GraphicsinterchangeDefs.Handle, 
box: GraphicslnterchangeDefs.Box, 
1 1 neProps : GraphicslnterchangeDef s.Li neProps] ; 

GraphicslnterchangeDefs.LlneProps: TYPE ■ 
LONG POINTER TO LlnePropsRec; 

GraphicslnterchangeDefs.LlnePropsRec: TYPE « RECORD [ 
brush : GraphicslnterchangeDefs.Brush, 
11 neEnd N W : GraphicslnterchangeDef s.Li neEnd, 
llneEndSE: GraphkslnterchangeDefs.LlneEnd, 
llneEndHeadNW: GraphksinterchangeDefs.LlneEndHead, 
lineEndHeadSE: GraphksinterchangeDefs.LineEndHead, 
direction: GraphicslnterchangeOefs.LineDirection 

]; 

GraphkslnterchangeDefs.LlneEnd: TYPE ■ MACHINE DEPENDENT 
{flush(O), square(l), round(2), arrow(3), (7)}; 

GraphkslnterchangeDefs.LlneEndHead: TYPE a MACHINE DEPENDENT 
{none(O), h1(1), h2(2), h3(3), (15)}; 

GraphkslnterchangeDefs.LlneDlrection: TYPE s MACHINE DEPENDENT 
{WE(0), NS(1), NwSe(2), SwNe(3)}; 

AddLlne adds a line to the graphics container at location 
box.piace. Thus, box is the parameter that describes the 
location of the line; you specify a line by specifying the box in 
which the line should fit. 

llneEnd* describe the properties of the ends of the curve. 
llneEndNW describes the end that is in the West, North, or 
North-West; llneEndSE describes the end that is in the East, 
South, or South-East. (Note that West and East take 
precedence, so an end in the SW is considered the NW end. See 
the example below.) 

If llneEnd = arrow, then llneEndHead describes the type of 
arrow: see Figure 18.2. If llneEnd narrow, then llneEndHead is 
none. 
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► 


h1 


► 


h2 


► 


h3 



Figure 18.2: Arrowheads 



wthbrush specifies the width of the line. As with frames, the 
standard widths are 35, 71, 106, 141, 176, and 212. 

Here is a fragment that creates the graphics frame in Figure 
18.3. Note that we have omitted the document creation code, 
which is the same as in the last example. 




Figure 18.3: Lines 



-set up line properties 

lineProps: GraphicslnterchangeDefs.LlnePropsRec <- [ 
brush: [wthbrush: 71,styiebrush: solid], 
lineEndNW: square, 
lineEndSE: square, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: NS]; 

-start graphics frame 

anchoredFrame <-GraphicsinterchangeDefs.StartGraphics[doc]; 
-add first line 

GraphicslnterchangeDefs.AddLlne [ 

h: anchoredFrame, 

box: [place:[x: 1129,y: 494], 
dlms:[w:0,h:2540]], 

lineProps: @lineProps]; 
-change properties 

lineProps <— [[106, solid], square, arrow, h1, none, SwNe]; 
-add second line 

GraphicslnterchangeDefs.AddLlne [ 

h: anchoredFrame, 

box: [place:[x: 2646, y: 635], 
dims:[w:2117,h:2081]l, 

lineProps: ©lineProps]; 
-finish up 

graphics <— GraphicslnterchangeDefs.FinishGraphics[ 
anchoredFrame]; 
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18.1.2.2 Rectangles and ellipses 



GraphicslnterchangeDefs.AddRectangle: PROC [ 
h : GraphicslnterchangeDefs.Handle, 
box: GraphicslnterchangeDefs.Box, 
rectangleProps: GraphksinterchangeDefs.RectangleProps] 

GraphicslnterchangeDefs.RectangleProps: TYPE ■ 

LONG POINTER TO GraphlcslnterchangeDefs.RectanglePropsRec; 

GraphicslnterchangeDefs.RectanglePropsRec: TYPE ■ RECORD [ 
brush: GraphicslnterchangeOefs.Brush, 
shad! ng : GraphksinterchangeDef s.Shadi ng] ; 

GraphicslnterchangeDefs-Shading: TYPE * RECORD [ 
g ray : Gra phicslntercha ngeDef s. G ray, 
textures: GraphicslnterchangeDefs.Textures]; 

GraphicslnterchangeDefs.Gray: TYPE > MACHINE DEPENDENT{ 
none(O), gray25{1), gray50(2), gray75(3), black(4), (1 5)}; 

GraphicslnterchangeDefs.Textures: TYPE ■ PACKED ARRAY 
GraphicslnterchangeDefs.Texture OF BOOLEAN; 

GraphicslnterchangeDefsTexture: TYPE a MACHINE DEPENDENT{ 
vertical(O), horizontal(l), nwse(2), swne(3), 
polkadot(4),(11)}; 

AddRectangle adds the rectangle whose shape is specified by 
box.dims to the graphics container at location box.place. 
AddEllipse is just like AddRectangle, except that it creates 
curved lines rather than straight lines, box.dims determine the 
size and shape of the ellipse; box.place determines its location 
relative to the frame. 



GraphicslnterchangeDefs-AddEllipse: PROC [ 
h : GraphicslnterchangeDefs.Handle, 
box: GraphicslnterchangeDefs.Box, 
el i i pseProps : GraphicslnterchangeOef s. El I i pseProps] ; 

GraphicslnterchangeDefs.EllipseProps: TYPE a LONG POINTER TO 
GraphicslnterchangeDefs.EllipsePropsRec; 



GraphicslnterchangeDefs.EllipsePropsRec: TYPE = RECORD [ 
brush: GraphicslnterchangeOefs.Brush, 
shadi ng : GraphicslnterchangeOef s.Shadi ng] ; 

For example, here is a call that creates the ellipse in Figure 18.4: 




Figure 18.4: Ellipse 
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-set up the ellipse props 

ellipseProps: GraphicslnterchangeDefs.EilipsePropsRec <- 
[brush: [wthbrush: 71,stylebrush:dashed), 
shading: [gray:none, 
textures: [true, false, false, false, false, false, false, false, 

FALSE, FALSE, FALSE.FALSE]]]; 

-add the ellipse to the graphics frame 
GraphicslnterchangeDef s. Add El I i pse [ 
h: anchoredFrame, 

box: [place:[x: 1000, y: 1000], dims:[w:2540, h:1000]], 
ellipseProps: ©ellipseProps]; 



GraphicslnterchangeOefs.AddCurve: PROC [ 
h: GraphicslnterchangeDefs.Handle, 
box: GraphicslnterchangeDefs.Box, 
CurveProps: GraphicslnterchangeOefs.CurveProps]; 

GraphicslnterchangeDefs.CurveProps: TYPE = LONG POINTER TO 

GraphicslnterchangeDefs.CurvePropsRec; 

GraphicslnterchangeDefs.CurvePropsRec: TYPE a RECORD [ 
brush: GraphicslnterchangeDef s. Brush, 
lineEndNW: GraphicslnterchangeDefs.LineEnd, 
lineEndSE: GraphkslnterchangeDefs.LineEnd, 
lineEndHeadNW: GraphksinterchangeDefs.LineEndHead, 
lineEndHeadSE: GraphksinterchangeDefs.LineEndHead, 
direction: GraphkslnterchangeDefs.LineDirection, 
placeNW, placeApex, placeSE, placePeak: 
GraphicslnterchangeDef s.Place]; 

In AddCurve, placeNW, placeApex, placeSE, and placePeak are 
the four points that define the curve, relative to box (and not 
the frameitself.) The apex of a curve is the intersection of the 
tangents; the peak is the "highest" point on the curve, where 
highest is defined as the farthest from the straight line that 
connects the endpoint. 

Figure 18.5 illustrates these four points for two different 
curves; the triangle marks the apex, the square marks the peak, 
and the circles mark the endpoints. The dotted lines on the 
lefthand curve indicate the lines used for determining the peak 
and apex. Also note that curves always paint clockwise, so you 
must make sure that the NW endpoint precedes the SW 
endpoint when tracing the curve clockwise. 



direction is ignored; you should always set this to WE. 



18.1.2.3 Curves 




A 



18.5: Defining curves 
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box specifies the location of the curve relative to the graphics 
frame. The function of box.dims is slightly different than in the 
previous Add* routines, however. Rather than defining the 
shape of the curve, box.dims specifies the part of the curve that 
is visible. Thus, if you define a curve that is larger than box, 
only the part of the curvethat fits within box.dims will appear. 

Here is an example that paints the three curves shown in Figure 
18.6. Notice that the box for the first curve is not large enough 
to contain the entire curve, so only the endpoint and the 
portion that fits within the box appear on the screen. However, 
the curves do print properly, so the printed version of this 
document will contain the entire curve. 




18.6: Curves 

set up some initial curve properties 

CurvePropS: GraphicslnterchangeOefs.CurvePropsRec <- 

[brush: [wthbrush: 71, stylebrush:dashed], 

lineEndNW: square, 

lineEndSE: square, 

lineEndHeadNW: none, 

lineEndHeadSE: none, 

direction: WE, 

placeNW: [0,71], 

placeApex: [1199,2681], 

placeSE: [1870, 0], 

placePeak: [1023,1129]]; 

-after setting things up, add a curve to the graphics frame 
GraphicslnterchangeDefs.AddCurve [ 
h: anchoredFrame, 

box: [place:[x: 1305, y: 988], dims:[w:1870, h:671]], 
-671 is too small for curve 
curveProps: ©curveProps]; 

-change the curve props and add another curve 
curveProps <- [[141, solid], square, square, none, none, WE, 

[1305,1235], [0,212], [1976,0], [917,423]]; 
GraphicslnterchangeDefs.AddCurve [ 

h: anchoredFrame, 

box: [place:[x: 2716, y: 2822], dims:[w:1976, h:1235]], 
curveProps: ©curveProps]; 

—and again: change props and add third curve 
curveProps ^ [[212, solid], square, square, none, none, WE, 

[0,0],[247,1094],[494,1799],[247,953]]; 
GraphicslnterchangeDefs.AddCurve [ 

h: anchoredFrame, 

box : [place : [5826,1 588], dims: [494,2000]] , 
curveProps: ©curveProps]; 
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18.1.2.4 Text frames 



There are also a number of Add* routines to add various types 
of frame objects to the graphics container. For example, here is 
the declaration of AddTextFrame: 

GraphicslnterchangeDefs.AddTextFrame: PROC [ 
h: GraphicslnterchangeDefs.Handle, 
box : GraphicslnterchangeDef s.BOX, 
frameProps: GraphicsinterchangeDefs.FrameProps, 
wantTextHandle, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRlghtCaptionHandie: boolean <~ false] 

RETURNS [ 

text: Text, topCaption, bottomCaption, 
leftCaption, rightCaption: DocinterchangeOefs.Caption]; 

GraphicslnterchangeDefs.Text: TYPE s LONG POINTER TO 
GraphicslnterchangeDef s.TextObject; - 

GraphicslnterchangeDef s.TextObject: TYPE; 

AddTextFrame adds a text frame to the specified graphics 
container. frameProps and want*CaptlonHandle are as 
described in section 18.1.1. If you specify wantTextHandle = 
TRUE, AddText will return a handle to a text frame. Once you 
have the handle to the text frame, you can call any of the 
Append*ToText routines below to add text to the text frame. 

GraphicslnterchangeDefs-AppendCharToText: PROC [ 
to: GraphicslnterchangeDefs.Text, 
char: xchar.Character, 

fontProps: FontPropsDefs.ReadonlyProps <-nil, 
nToAppend: cardinal <- 1]; 

GraphicslnterchangeDefs.AppendFleldToText: PROC [ 
to: GraphicslnterchangeDefs.Text, 
fleldProps: FieldProps, 
fontProps: FontPropsDefs.ReadonlyProps <-nil] 
RETURNS [field: DoclnterchangeDefs.Fieldj; 

GraphicslnterchangeDefs-AppendNewParagraphToText: PROC [ 
to: GraphicslnterchangeDefs.Text, 
paraProps: ParaPropsDefs.ReadonlyProps <-nil, 
IFontProps: FontPropsDefs.ReadonlyProps <-n[l, 
nToAppend: cardinal «- 1]; 

GraphicslnterchangeDef s.AppendTextToText: PROC [ 
to: GraphicslnterchangeDefs.Text, 
text: xstring.Reader, 
textEndContext: xstring.Context, 
fontProps: FontPropsDefs.ReadonlyProps <-nil]; 

These routines are just like the Append routines in 
DoclnterchangeDefs; see Section 17.1.1 for more information. 

If you receive a valid text handle from AddTextFrame, you must 
eventually call ReleaseText to return the storage: 
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GraphicslnterchangeDefs.ReleaseText: PROC [ 

textPtr: LONGPOINTERTO GraphkslnterchangeDefs.Textl; 

ReleaseText releases handles obtained from AddText. Like 
Mesa's free operator, these routines take a pointer to the 
object to be freed, and set the handle itself to nil. Thus, after a 
call to ReleaseText, text will be nil. 

Here is a code fragment to create the text frame shown in 
Figure 18.7: 




Figure 18.7: Text frame 



text: GraphicslnterchangeDefs.Text <— nil; 

content: xstring.ReaderBody «-xstrmg.FromSTRING[ 

"There's a first time for everything. "L]; 
set up text frame props 

textframeProps: GraphicslnterchangeOefs.FramePropsRec «- 

[brush: [35, solid], 

expandRight: true, 

expandBottom: true, 

margins: [0,0,0,0], 

captionContent: [nilnilnilnil]]; 
"Set up character props for content of text frame 
f ontProps : FontPropsOef s.PropsRecord ; 
DocinterchangeDefs.GetFontPropsDefaults[@fontProps]; 
fontProps.fontDesc.pointSize <- 10; 



-after setting up graphics frame, add text frame to it 
[text] «-GraphicslnterchangeDefs.AddTextFrame [ 

h: anchoredFrame, 

box: [place:[x: 1058, y: 847], 
dims:[w:3563, h:706]], 

frameProps: @textFrameProps, 

wantTextHandle: true]; 
--initialize contents of text frame 
GraphicslnterchangeDefs.AppendTextToText[ 

to: text, 

text: ©content, 

textEndContext: XString.unknownContext, 
f ontProps: @f ontProps]; 
-release text handle 

GraphicslnterchangeDefs.ReleaseText[@text]; 
. . .--finish graphics frame and document 



18.1.3 Finish routines 



When you are through adding things to a new graphics frame, 
the last step is to call a Finish routine: 

GraphicslnterchangeDefs.FinishCluster: PROC [ 
ch: GraphkslnterchangeDefs.Handle]; 
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GraphicslnterchangeDefs.FinishGraphics: PROC[h: Handle] RETURNS [ 

graphics: instanceDefs.lnstance]; 

GraphicslnterchangeDefs.FinishGraphicsFrame: PROC [ 
gfh: GraphicslnterchangeDefs.Handle]; 

ch, h, and gfh are the handles obtained from the 

corresponding Start routines. Typically you will pass the 

InstanceDefs.lnstance returned by FinishGraphics to 
DocinterchangeDefs.AppendAnchoredFrame. 



18.2 Reading graphics 



You can also use GraphicslnterchangeDefs to read the contents 
of graphics frames. To read a graphics frame, you start by 
calling GraphicsinterchangeDefs.Enumerate, which takes as 
parameters a graphics container and a record of call back 
procedures, one for each of the kinds of things that might be in 
the graphics container: bitmap frame, cusp button, cluster, 
curve, ellipse, form field, frame, image, line, point, rectangle, 
text, triangle, other. 

Enumerate proceeds through the contents of the graphics 
container, calling the appropriate procedure for each object 
that it encounters. If you don't provide a procedure for a 
particular type of object, the enumeration will ignore objects 
of that type. 

GraphicslnterchangeOefs.Enumerate: PROC [ 
doc: DoclnterchangeDefs.DOC, 
graphlcsContainer: instanceDefs.lnstance, 
prOCS : Gra phicslntercha ngeDef s . E n U m Procs , 
clientData: LONG POINTERS- nil] 
RETURNS [dataSkipped: boolean]; 

GraphicslnterchangeDefs. En umPrOCS: TYPE = LONG POINTER TO 
GraphicslnterchangeDef s. E n u mPrOCS Record ; 

GraphicslnterchangeDefs.EnumProcsRecord: TYPE a RECORD [ 
bltmapPrOC: GraphkslnterchangeDefs.BitmapProc «-NIL, 
buttOnPrOC: GraphkslnterchangeDefs.ButtOnProc <-NIL, 
clusterPrOC: GraphicslnterchangeDefs.ClusterProc <-NIL, 
CUrveProc: GraphkslnterchangeDefs.CurveProc <-NIL, 
eliipsePrOC: GraphkslnterchangeDefs.EllipseProc ^-NIL, 
formFleidProc: GraphkslnterchangeDefs.FormFieldProc «-nil, 
frameProc: GraphkslnterchangeDefs.FrameProc <-NIL, 
imageProc: GraphkslnterchangeDefs.lmageProc <-nil, 
lineProc: GraphkslnterchangeDefs.LineProc <-NIL, 
OtherProc: GraphkslnterchangeDefs.OtherProc <— nil, 
pointProc: GraphicslnterchangeDefs.PointPrOC <-NIL, 
rectangleProc: GraphksinterchangeDefs.RectangleProc <-nil, 
textFrameProc: GraphicsinterchangeDefs.TextFrameProc ^nil, 
trIangleProc: GraphksinterchangeDefs.TriangleProc <-nil]; 

Each enumeration procedure takes parameters that describe 
the properties of the object. These properties are temporary, 
which means that you shouldn't try to release the storage 
associated with them. It also means that you must explicitly 
copy any properties that you wish to save, since they will be 
destroyed destroyed after the procedure returns. You 



18-12 



VIEWPOINT PROGRAMMING COURSE 



GRAPHICS 



In the case of a cluster, or nested graphics frame within an 
anchored frame, you can recursively call Enumerate to get the 
contents of the nested object. 

Here are the declarations of some of the enumeration 
procedures; see the ViewPointProgrammer's Manual for the 
complete documentation: 

GraphicslnterchangeDefs.CluSterProc: TYPE a proC [ 

cilentData: long pointer, 
graphicsContainer: instanceoefs.lnstance, 
box: GraphicsinterchangeDefs.Box] 
RETURNS [stop: BOOLEAN <- FALSE]; 

GraphicslnterchangeDefs.CurveProc: TYPE ■ PROC [ 

cilentOata: long pointer, 

box : GraphicsinterchangeDef s. Box, 

CUrveProps: GraphkslnterchangeOefs.CurveProps] 

RETURNS [stop: BOOLEAN <- FALSE]; 

GraphicslnterchangeDefs. Ell ipsePrOc: TYPE ■ PROC [ 

clientData: long pointer, 

box: GraphicsinterchangeDefs.Box, 

el 11 psePropS : GraphicsinterchangeDef s.Ell i pseProps] 

RETURNS [stop: BOOLEAN FALSE]; 

GraphicslnterchangeDefs.FramePrOc: TYPE a PROC [ 

clientOata: long pointer, 
graphicsContainer: instanceDefs.instance, 
box : G ra phicsl ntercha ngeDef s. Box, 
frameProps: FrameProps] 

RETURNS [stop: BOOLEAN <- FALSE]; 

GraphicslnterchangeDefs.LineProc: TYPE s PROC [ 
clientData: long pointer, 
box: GraphicsinterchangeDefs.Box, 
llneProps: GraphicslnterchangeDefs.LlneProps] 
RETURNS [stop: BOOLEAN <- FALSE]; 

GraphlcslnterchangeDefs.PointPrOc: TYPE ■ PROC [ 

clientData: long pointer, 

box: GraphicsinterchangeDefs.Box, 

pointProps: GraphicsinterchangeDef s.PointProps] 

RETURNS [stop: BOOLEAN <- FALsE]; 

GraphicslnterchangeDefs.RectangleProc: TYPE a prqc [ 
clientData: long pointer, 
box: GraphicsinterchangeDefs.Box, 
rectangleProps: GraphicsinterchangeOefs.RectangleProps] 
returns [stop: boolean false]; 

GraphicslnterchangeDefs.TextFrameProc: TYPE a PROC [ 

clientData: long pointer, 

box: GraphicsinterchangeDefs.Box, 
frameProps: GraphicslnterchangeDefs.FrameProps, 
content: GraphicsinterchangeDef s.Text] 
RETURNS [stop: boolean <- false]; 

GraphicslnterchangeDefs.TriangleProc: TYPE = PROC [ 

clientData: long pointer, 

box: GraphicsinterchangeDefs.Box, 

triangleProps: GraphicslnterchangeDefs.TriangleProps] 

returns [stop: boolean <- false]; 
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1 8.2.1 Enumerating text frames 



There is also a related enumerator, EnumerateText, that takes 
as parameters a text frame and a record of procedures to 
handle the various kinds of information that can be in a text 
frame: fields, new paragraphs, and text. 

GraphicslnterchangeDefs.EnumerateText: PROC [ 
text: GraphicslnterchangeDefs.Text, 
prOCS: GraphicslnterchangeDefs.TextEnumPrOCS, 

cllentData: long pointers- nil] 
RETURNS [dataSkipped: boolean]; 

GraphicslnterchangeDefs.TextEnumPrOCS: TYPE a LONG POINTER TO 
GraphicslnterchangeDefs.TextEnumProcsRecord; 

GraphicslnterchangeDefs.TextEnumProcsRecord: TYPE ■ RECORD [ 
fleldPrOc: DoclnterchangeDefs.FleldProc ^NIL, 
newParagraphProc: 

DocinterchangeDefs.NewParagraphProc <- NIL, 
textProc: DoclnterchangeOefs.TextProc <-NIL]; 

EnumerateText enumerates the contents of a text frame, 
calling the client-supplied EnumProcs as appropriate. 



18.3 Summary 



Creating new graphics and inserting them in a document 
involves the following steps: 

1. Call DocinterchangeDefs.StartCreation to get a document 
handle (doc.) 

2. Call StartGraphics[doc] to get an anchored frame handle 
(h). 

3. Call Add*[h] to add graphics to the anchored frame. 

4. Call FinishGraphics[h] to complete the anchored frame 
and get an object of type instanceoefs.lnstance (graphics). 

5. Call DocinterchangeDefs.AppendAnchoredFrame[graphics], 
optionally receiving caption handles in return. 

6. Call DocinterchangeDefs-Append* to add information to the 
captions. (Optional.) 

7. Call DocinterchangeDefs.FinishCreation[@doc]. 

Enumerating the contents of an existing graphics frame 
involves the following steps: 

1 . Call DocinterchangeDefs.Open to open the document 

2. Call DocinterchangeOefs.Enumerate, passing in a 
DocinterchangeDefs.AnchoredFrameProc to handle any 
graphics frames within the document. 

3. Within the DocinterchangeDefs.AnchoredFrameProc, call 
GraphicsinterchangeDefs.Enumerate, passing in procedures 
for any graphic objects of interest. 

4. Call DoclnterchangeDefs.Close. 
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A. PROGRAMMING IN VIEWPOINT 



This appendix describes some miscellaneous information that 
you will need to know about running and debugging a new 
Viewpoint application. You need to have finished the XDE 
tutorials before you read this appendix. 

If you have never run a Viewpoint application before, you 
should read this appendix before you start the course. If you 
have, you might want to skim this anyway. 



A.1 The programming cycle 



When you program in the Xerox Development Environment 
(XDE), there are two possible "target environments": XDE and 
Viewpoint. When you want to write new applications for XDE 
itself, you write the application in CoPilot, test it in Tajo and 
debug in CoPilot until it works, and then eventually run in it 
CoPilot alongside other XDE tools. 

When you program for Viewpoint, you write the code in 
CoPilot, test it in ViewPoint, debug in CoPilot, and then 
eventually run it in ViewPoint alongside other applications. 

When you are testing a new Viewpoint application, you need 
to copy the code to ViewPoint and then run it there. There are 
two ways to do this: you can copy the code from XDE to 
ViewPoint with CommandCentral, or you can put the code in a 
remote file drawer from XDE and then retrieve it from 
Viewpoint. During development, you can use either method. 
Once you are through with your application, however, you 
should put it on a file server so that others can access it. (See 
the XDE User's Guide for more information on 
CommandCentral, the debugger, the editor, the compiler, and 
the binder.) 

One thing to remember when you are testing an application is 
that loading an application does not produce any visible 
results. As discussed in Chapter 2, User interface, an application 
can run either from a command in the Attention Menu or from 
an icon on the desktop. If the application runs from a 
command in the Attention Menu, you need to bring up that 
menu before you see the command. If the application runs 
from an icon, you will have to open the Prototype folder and 
copy the icon onto your desktop. Applications do not place 
icons directly on the desktop: that is the user's prerogative. 



A.2 The Workstation Profile 



As mentioned in the introduction, you need to have a 
Workstation Profile on your machine. This file specifies 



VIEWPOINT PROGRAMMING COURS 



A-1 



PROGRAMMING FOR VIEWPOINT 



whether or not you are a "developer"; being a developer gives 
you certain privileges that customers do not have. Your 
WorkstationProfile should look like this: 

[System] 
Developer: true 

[Application Loader] 
Developer: true 

You might also want to have a UserProfile, which allows you to 
set defaults for various tools. The course does not depend on 
one, however. 



A.3 The SystemFolder 



Every file on your ViewPoint system must be either on the 
desktop or in the system directory. The SystemFolder 
application provides access to all files in the System directory. If 
you do not run this application, files will be in your System 
directory, but you will not have any way of accessing them. 

When run, SystemFolder registers the System Folder command 
in the Attention Menu. Invoking the System Folder command 
opens a window showing the contents of the System folder, 
including object files, TIP files, font files, and icon picture files. 
You can then copy those files onto your desktop, or onto the 
loader, as described in the next section. 

The SystemFolder application also registers a third command, 
Prototype Folder, which provides easy access to the Prototypes 
folder. 



A.4 The Application Loader 



Copying files from XDE via CommandCentral is one way to run 
an application; the other way is to use the Application Loader 
to load and start programs directly from Viewpoint. To use the 
Application Loader, you must have a Loader icon on your 
desktop. If you don't, open the Directory icon, and then the 
User folder. Inside the User folder you will find the Loader icon; 
copy it to your desktop. You can then copy or move object code 
icons (beds) or application icons to the Application Loader for 
subsequent loading and starting, with associated feedback 
appearing in the Attention window. 

Using the Application Loader in conjunction with the 
SystemFolder application makes it very easy to load files that 
are in the System directory. You just open the System folder, 
select the desired files, and move or copy them to the Loader 
icon. 

You can also load applications directly from remote file 
drawers. To do so, just open the file drawer, select the 
application, and copy it either directly to the Loader or onto 
your desktop. 

Opening the Loader icon will show all the applications on the 
workstation and their status; that is, whether they are idle or 
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running. An additional way of running a program that is on 
the desktop but not yet started is to select it from within the 
open Loader icon and select the Run command in the header of 
the Loader window. 

You should note, however, that the term application is a loose 
one; there is actually a difference between a file of object code 
and something called an application folder. An application 
folder is a complete application; it always contains at least one 
bed file, but it can also contain other items such as information 
on the picture that will appear on the icon, messages that the 
application will post to the user, and other supplementary 
information. A bed file is a single file of object code. 
Application folders represent finished applications; beds often 
represent applications that are still under development. Thus, 
"standard" applications such as the document editor are 
actually application folders; applications with the extension 
.bed are object files. (Chapter 16, Application folders, discusses 
application folders in detail.) 

This distinction is important because the Loader looks for the 
following entry in the Workstation Profile: 

[Application Loader] 
Developer: true -or false 

If the Developer value is true, the opened Loader icon will 
show application folders and beds. If Developer is false, it will 
only display application folders. 



A.5 .autorun files 



At boot time, the loader looks in the system catalog for files 
with an extension of .autorun and automatically loads and 
starts any files with that extension. Thus, commonly used tools, 
such as SystemFolder, usually have the .autorun extension. To 
change a file's extension to .autorun, either name it that way in 
XDE and use CommandCentral to copy it into the System 
folder, or change its name in Viewpoint by selecting it within 
the System folder and modifying its name via its property 
sheet. If you rename the file from XDE and use 
CommandCentral to copy it to Viewpoint, you must use the /-e 
client switch in CommandCentral. If you don't, ViewPoint will 
attempt to start it twice, which will cause problems. 

Note also that there are built-in applications that are always 
run automatically. Such applications are not the same as 
.autorun applications, because you do not get to choose 
whether they are run. Such applications are referred to as 
invisible applications, because they appear even when not 
explicitly run. The Wastebasket and the Directory are examples 
of invisible applications. 
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Notes: 
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ICON EDITOR 



The icon editor is a tool that allows you to create icon files for 
inclusion in an application folder. 



B.1 Getting started 



To use the icon editor, make sure that you have the files 
BWSIconEditor.bcd and Standard. icons in your system folder. If 
they are not there, you can add them either by copying them 
from a file drawer, or by running them from Command Central 
using the/-e switch. 

Once you have these two files in the system folder, you need to 
do the following: 

1. Open your System folder and copy Standard. icons to your 
desktop. Standard. icons contains a list of the icons currently 
available, and the file types with which those icons are 
associated. 

2. Use the props key to rename the copy of Standard. Icons that 
is on your desktop to be New.icons, and change the file type 
to be 6010. (The new name that you choose is arbitrary; in 
fact, you don't even have to rename it. However, the new 
file type must be 6010.) 

The basic idea is that you create a new icon by modifying an 
existing icon. Once you have the new icon, you can use it for 
any application. There is nothing to prevent you from 
modifying Standard. icons directly, without copying it; 
copying the file just protects you from accidentally 
overwriting an existing icon. 

3. Move or copy BWSIconEditor.bcd to the Loader. 

4. Open the New.icons file, and you will get a list of icons and 
associated file types. Choose an icon that you want to 
modify, and open it. If you want to modify one of the 
standard icons, you should open that icon; if you want to 
create a new one, you can select any of them to modify. 

When you open an icon, you will get a list of sizes, such as 8 
X 8 or 65 X 65. These sizes correspond to the various possible 
forms of that icon, such as tiny, cursor, and reference. Select 
the size that you want to modify and open it to start editing. 
(See the Viewpoint Series Reference Library for more 
information on icons.) 

The next section desribes the available editing commands. 

5. When you have finished editing the file, invoke the Save 
command. You then have a file called new.icons that 
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contains your new icon. You can delete all the other icons in 
the file, and then include new.icons in an application folder, 
as described in Chapter 1 6, Application Folders. 



B.2 Editing the icon 



While you are editing an icon file, you have the following 
operations available: 

Left mouse button Make a white box black 

Right mouse button Make a black box white 

Magnification Change the size of the icon. Provides 

a popup menu that allows you to 
choose the power of the 
magnification. 

Shift Shift the current bitmap pixel by 

pixel. Supplies a menu that allows 
you to specify the direction of the 
shift. 

Save Save the current bitmap in a file. You 

should use this command when you 
have finished editing. 

Reset Restore a bitmap to its original 

condition (before any edits) 

Clear Clear bitmap completely 

You can also use the props key to change the dimensions of the 
text box (where the icon name is displayed.) To do this, select 
an icon from the list of icons in the .icons file, and press props. 
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This chapter describes tools for creating, modifying, and 
translating message files. There are three related tools: the 
Message Master File Creation tool, the Message Master Editor, 
and the Message Runtime File Creation tool. 

The Message Master File Creation Tool takes a message bed 
and generates a Message Master file. A Message Master file 
contains the original text, a translation of that text, and 
additional information for the translator. You can then modify 
or translate those messages with the Message Master Editor. 

Finally, once you have finished editing your messages, you 
need to use the Message Runtime File Creation Tool. This tool 
builds a Message Runtime file from a Message Master file. The 
runtime file ("compiled version") contains information for a 
running application; it cannot be edited. 



C.1 Message Master File Creation Tool 



To create a message master file, the first step is to run 
MasterFlleCreate.bcd; this will create an icon identified by the 
words "Msg Master Maker." Next, copy the file containing your 
message information to this icon. (The file with the message 
information is the compiled version of the message 
implementation; it can be either a single file or a folder with 
several files. See Chapter 3, Strings and Messages.) 

When you copy a file to the Message Master icon, an options 
window appears that allows you to specify the application 
name, language, and version. The default application name is 
the name of the Message bed file or folder. The default 
language is US. You must specify a version number, however; 
there is no default Figured illustrates this option sheet. 




Figure C.1 Message Master Creation Tool 



To create the Message Master file, select Start in the tool 
window header. If you do not enter a version number, you will 
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get an error message; the message master creation process will 
not continue until you enter a version number and select Start 
again. During file creation, the window disappears from the 
screen. Until the window disappears, you can abort the 
operation by selecting Cancel in the tool window header. 

This tool produces an icon identified by the name of the 
application, as illustrated in Figure C.2. 



4418 
SampleAppI 
icationMsgl 
mpl.bcd.1.0. 
US.Master 



Figure C.2 Master File icon 



The name of the Message Master file will be: 

< Application Name > .< version > . < language > .master 

For example: Cusp.3.3I.US.master is the Message Master file 
for version 3.3i of the application Cusp. Its language is US. 

The Message Master Creation tool also produces an errorlog 
and places it on the desktop. The possible errors are: 

• Duplicate IDs: This error indicates that a set of 
MessagelmpI beds has messages in identical domains 
with identical IDs. This error means that the source will 
have to be changed and recompiled. (See Chapter 3, 
Strings and Messages, for a discussion of IDs.) 

• Unbound Procedure: This error indicates that a 
MessagelmpI bed contains references to other beds that 
are not bound in. To fix this, you must remove the 
offending unbound reference or bind the files with the 
appropriate implementation. 

• No domains: This error indicates that the MessagelmpI 
bed contains no calls to xMessage.AlloeateMessages or 
XMessage.RegisterMessages. 

• RegisterMessages/AllocateMessages Error: This error 
indicates that the bed has either called 
XMessage.AlloeateMessages and 
XMessage.RegisterMessages in the wrong order or has 
only referenced one of them. 

The message master file contains an untranslated version of all 
the messages. Once you have this file, you can either edit the 
messages with the Message Master Editor, or you can go 
directly to the last step, creating a runtime ("compiled") 
version of the file. Typically, you won't need to edit the 
Message Master file when you first create it, but you may later 
need to changes the messages and create a new runtime 
message file. Section C.3 discusses the Message Master Editor; 
Section C.4 discusses the Message Runtime File Creation Tool. 
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C.2 Message File property sheet 



There is also a property sheet associated with each Message 
Master file. To display the properties of a file, select the 
corresponding Message File icon and press the props key. The 
property sheet that appears is shown in Figure C.3. 




Application 



Name: 

Application Name 



Date Created : dd-m m-yy 



Last Edit on dd-mm-yy 



Previous Message Master 



File for finding changed messages 



Automatic Save 



No. of Keys Edited before save: 



Figure C.3 Message Master property sheet 



You can use this property sheet to change the application 
name, frequency of automatic save, and so on. For more 
information on any of the fields in this property sheet, see the 
complete Message Tools documentation. 



C.3 Message Master Editor 



Once you have the message master icon, you can edit its 
contents with the Message Master Editor. To use this tool, load 
the program MessageFlleTooi.bcd. The editor allows you to 
search, edit, translate or print the text of the messages. To edit 
a message master, select the icon and press open. This will bring 
up the editor window, as illustrated in Figure C.4. 
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Window for Editor Messages e.g. message has incorrect parameters 



Create iVlsg File 
Print Messages 
Search Archive 
Check Msg File 



First Instance 



Next Instance 



Backward 



Find Msg using 



Sequential 



New 



Untranslated 



Translated 



illllliii 



Deleted 



Parameters 



Current Message 

Key: 27 

I 

Status: Untranslated Msg Type: menultem Translatable: Yes 

Old US Message: Text of old meisage (only for "changed" messages) 

US Message: Text of new message 



Translation 
Note: 



Editable field for message translation 



Implementor's note to the translators. 



Figure C.4 Message Master Editor window 



Using this window, you can edit the current message, and 
change the current message using various search criteria. For 
example, you can examine and potentially modify any new 
messages, or all untranslated messages, or the like. 



C.3.1 Searching Message Master files 



To search the message file to find a message that satisfies a 
particular criterion, use the commands Firstlnstance and 
Nextlnstance. First Instance searches the Message Master file 
from the beginning to find and display the first message that 
satisfies the given search criteria. Next Instance finds the next 
instance (going either forward or backward from the last 
successful search) of the specified message type. You can also 
execute this command by pressing the next key. 

The Find Msg Using field allows you to specify the type of 
message searched for. The search proceeds either forward or 
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backward, depending on the value selected in the form 
window. The choices are: 



Sequential finds the first or next message in the file. 

New finds the next message with the status 

"new." 

Untranslated finds the next message with the status 
"untranslated." 



Translated finds the next message with the status 

"translated." 



Changed finds the next message with the status 

"changed." If an entry of this type is 
found, an additional field appears that 
contains the previous version of the 
original text. (This field is not displayed for 
other types of messages.) If you have not 
specified the previous original text in the 
file properties, an error message appears 
and no text is displayed. 

Deleted finds the next message with the status 

"deleted." 



Parameters displays a set of options that specify the 
search criteria. See Section C.2.2 for 
details. 



If no message of the type specified can be found, "No message 
Found" appears in the Message window and the currently 
displayed message remains in the tool window. 



C.3.2 Search parameters 



You can also search by parameter. When you select the 
parameters option, a section on search parameters will appear, 
as illustrated in Figure C.5. A search is successful only if all 
specified criteria are met. If you specify Message Text, you can 
search for the original text (by specifying US) or for a 
translation of the original text (by specifying Trans). 
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Window for Editor Messages e.g. message has incorrect parameters 



Create Msg File 
Print Messages 
Search Archive 
Check Msg File 



First Instance 



Next Instance 



liSiiiiiiiiiiliii 



Backward 



Find Msg using 



Sequential 



New 



Untranslated 



Translated 



Changed 



Deleted 



Current Message 

Key: 27 



ID: 



25 



Status: Untranslated Msg Type: menultem Translatable: Yes 

Old US Message: Text of old message (only for "changed" messages) 

US Message: Text of new message 



Translation 
Note: 



Editable Field for message translation 



Implementor's note to the translators. 



Search Parameters \ 

Key: 



Key No. 



my ON 



ID No. 



mm. 



Message Text: 



Field for message text 



Orig 



Status: 



Msg Type: 



New Changed Translated Deleted 



Untranslated liifiil 



userMsg 



template 



argList 



menultem 



pSheetltem 



Figure C.5 Searching by parameter 



Simple searches by Key, ID, Status field, or Msg Type are 
reasonably quick. However, specifying the Key or ID fields in 
conjunction with other .fields is slow and unproductive, as 
these fields are specific to the message. 

When searching for strings (either translated or original text), 
setting the Status field or the Msg Type field accelerates the 
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search. String searches are based on a search for the substring 
entered in the Message Text field. 

When a search is successful, a message appears with 
information about the message. See the complete Messate 
Tools documentation for more information. 



C.3.3 Closing, saving, and resetting 



Once you have edited a message file, there are three ways to 
save the resulting file: 

1 Use the Save command in the main window header. This 
function saves all changes made since the file was 
opened (or since the last save command.) 

2 Use the Automatic Save function in the Message File 
property sheet. See section C.2 for details. 

3 Use the Close command. This function closes the edit 
window and saves any changes made to the file since it 
was opened or since the last save. 

You can also use the Reset command to restore a file to its last 
saved state. If you have changed the file, you must confirm the 
command (by reselecting the Reset command.) 



C.3.4 Printing message files 



To obtain hardcopies of information contained within the 
Message Master, use the Print Messages command in the 
auxiliary menu of the Message Editor. This command displays a 
list of print options, as illustrated in Figure C.6. 




Print Messages: 



Translated 



Untranslated 



Changed 



New 



Deleted 



VferfeUS^ Terse 



Figure C.6 Print options 



Selecting Start produces an Interpress master and sends it to 
the printer specified in the Printer Name field. You can print all 
messages or a category of messages. (The category can be 
translated, untranslated, changed, hew, or deleted.) 
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In addition, you can specify verbose or terse. Verbose produces 
a document containing all available information (original text, 
translated text and translation information.) Terse produces a 
document containing only the original text, message key 
number, and message ID. 



C.4 Runtime File Creation Tool 



The final step is to create a Runtime Message file. A Runtime 
Message file is essentially a compiled version; it can be loaded 
with an application, but it can't be edited or viewed. You can 
run this program either from the auxiliary menu of the 
Message Master Editor, or as a tool in its own right. In either 
case, you need to run the program RuntimeFlieCreate.bcd. 

To run this tool from the Message Master Editor, select the 
Create Message File command from the auxiliary menu. This 
command creates the window illustrated in Figure C.7. 




Figure C.7 Using the Create Message File command 

This window allows you to specify the type of text (original or 
translated) in the Runtime Message file. If you specify Original, 
the Runtime Message file will contain only the original text. If 
you specify Translated, the command Runtime Message file 
will contain only the translated text. 

The Runtime Message file is produced when you select Start. 
The resulting file appears as an icon on the current desktop. As 
illustrated in Figure C.8, this icon is just like the message master 
icon, except that its name ends in .Runtime instead of .Master. 
You cannot perform any operations on the runtime file. 



Master File Icon 



Runtime File Icon 



4418 



SampleAppI 
icationMsgl 
mpl.bcd.1.0. 
US. Master 



4418 



SampleAppI 
icationMsgl 
mpl.bcd.1.0. 
US. Runtime 



Figure C.8 The resulting icon 
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To create a Runtime Message file without using the IVIessage 
File Editor, use the Runtime IVIessage Creation tool. The icon 
for this tool is identified by the words "Runtime Msg Maker". 
Use the copy key to copy a Message Master file containing the 
message information to this icon. The tool then produces an 
original language Runtime Message file with the same name as 
the Message Master file followed by the extension .messages. 

When the operation is complete, the tool places a Runtime 
Message file on the desktop. 
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Notes: 
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MenultemProc, 8-3 



MenultemType, 8-2 
optionSheetDefaultMenu, 8-2 
propertySheetDefaultMenu, 8-2 
SwapExistingFormWindows, 8-7 
SwapForm Windows, 8-6 

Prototype interface 
Create, 15-11 
Find, 15-11 

prototype catalog, 1 1-4 

Prototype folder, 2-6 



readers, 3-2 

accessing contents of, 3-4 

creating, 3-4 

vs. readerBodys, 3-4 
rectangles 

adding to graphics frame, 18-5 
reference (to file), 11-1 
remote files, 11-5 
requestors (selection), 14-1 
results (in TIP table), 9-4 
Runtime File Creation Tool, C-8 
Runtime Message Files, C-8 
RuntimeFileCreate.bcd, C-8 



segments (of files), 13-3 
Selection interface 

CanYouConvert (Def), 14-5 

CanYouConvert (Ex), 14-6, 14-7 

Convert (Def), 14-1 

Convert (Ex), 14-2, 14-4 

Copy 14-3 

CopyMove, 14-3 

CopyOrMove, 14-3 

Difficulty, 14-5 

Enumerate, 14-6 

EnumerationProc, 14-6 

Free, 14-3, 14-5 

HowHard, 14-5 

maxStringLength, 14-6 

Move, 14-3 

nullValue, 14-1 

RequestorData, 14-6 

Target, 14-1 

UniqueTarget, 14-2 

Value, 14-1 

ValueCopyMoveProc, 14-3 
ValueHandle, 14-3 
selection 

copying (Ex), 14-4 

copying streams, 14-5 

defining new target types for, 14-2 

enumerating, 14-6 

example, 14-2 

is conversion possible?, 14-5 
managers, 14-1 
monitoring, 14-3 
Notifier and, 14-3 
obtaining, 14-1 
requestors, 14-1 
target types for, 14-2 
session, 10-8 
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SimpieTextDispiay interface 

StringlntoWindow, 6-4 
SimpleTextFont interface 

AddClientDefinedCharacter (Def), 15-5 

AddClientDefinedCharacter(Ex), 15-6, 15-13 
SIZE (Ex), 12-6, 13-7 
size attributes, 10-2 
Space interface 

Error, 13-7, 13-12 

ForceOut, 1 3-6 

Interval, 13-2 

ScratchMap, 15-4 

Unmap(Def), 13-5 

Unmap(Ex), 13-6, 13-7, 13-12 
Star Desktop interface 

AddReferenceToDesktop, 17-7 

GetCurrentDesktop, 14-4 
StarWindowShell interface 

AddPopupMenu , 4-9 

AdjustProc, 6-1 1 

Create (Def), 4-3 

Create (Ex), 4-4, 4-6, 4-11 

CreateBody (Def), 4-5 

CreateBody (Ex), 4-6, 4-1 1 

GetAdjustProc, 6-11 

GetLlmitProc, 6-11 

GetZone, 4-8, 4-11 

Handle, 4-3 

IsCloseLegalProc , 4-4 

LimitProc, 6-10 

Pop, 4-10 

Push, 4-1 2 

SetAdjustProc, 6-1 1 

SetLlmitProc, 6-1 1 

SetRegularCommands (Def), 4-8 

SetRegularCommands (Ex), 4-8, 4-12 

Standard LimitProc, 6-1 1 

State, 4-4 

TransitionProc , 4-4 

When, 6-11 
StarWindowShell 

adding commands to (Ex), 4-8 

creating, 4-2 

creation of (Ex), 4-1 1 
Stimulus, 9-1 
Stream interface, 12-1 

Block, 12-4 

Delete (Def), 12-8 

Delete (Ex), 12-3, 13-16 

EndOfStream, 12-3 

GetBlock (Def), 12-4 

GetBlock (Ex), 12-6 

GetByte, 12-3 

GetPosition, 12-7 

GetWord, 12-3 

Handle, 12-2 

Object, 12-2 

Position, 12-7 

PutBlock (Def), 12-4 

PutBlock (Ex), 12-6, 13-16 

PutByte, 12-2 

PutWord, 12-3 

SetlnputOptions, 12-6 

SetPosition, 12-7 



streams, 12-1 

as target of selection, 14-5 
block example, 12-6 
counting bytes of, 12-7 
creating, 12-2 
deleting, 12-8 

example of end of stream, 1 2-3 
10 example, 12-3 

miscellaneous operations on, 12-7 

random access, 12-7 
strings, 3-1 
swap unit, 13-1 
swapping, 13-1 
syntax 

forADF, 16-2 

of TIP tables, 9-3 
system catalog, 1 1-4 
system directory, A-2 
System Folder, A-2 
SystemFolder application, 2-7 

T 

tagonly item 

in form window, 7-2 
TakeSelection, 15-7 
TakeSelectionCopy, 15-7 
temporary file, 1 1-7 
Terminal Interface Package 

see TIP, 9-1 
text frames 

adding contents to, 18-10 

creating, 18-10 

reading contents of, 18-14 

releasing storage, 18-11 
text item 

creating, 7-4 

in form window, 7-2 
tiled windows, 2-3 
timeout 

for file access, 11-2 
TIP interface 

AttentionProc, 9-15 

CreatePeriodicNotify, 9-14 

CreateTable (Def), 9-7 

CreateTable (Ex), 9-8, 9-12 

InvalidTable (Def), 9-8 

lnvalidTable(Ex),9-12 

LosingFocusProc, 9-10 

NotifyProc (Def), 9-6 

NotifyProc (Ex), 9-6, 9-12 

PeriodicNotify, 9-14 

ResetUserAbort, 9-15 

ResultObject, 9-4 

Results, 9-4 

SetAttention, 9-15 

SetlnputFocus, 9-10 

SetTableAndNotifyProc (Def), 9-9 

SetTableAnd NotifyProc (Ex), 9-12 

Table, 9-7 

TableError, 9-8 

TableObject, 9-7 

UserAbort, 9-15 
TIP files 

in application folder, 16-7 
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TIP tables, 9-1 

associating with windows, 9-9 

creating (Ex), 9-8 

example of, 9-4, 9-1 1 

incorporating, 9-7 

normal, 9-2 

NotifyProcs and, 9-9 

results lists, 9-4 

syntax of, 9-3 
TIPC files, 9-8 
TIPStar interface 

NormalTable, 9-9 

Placeholder, 9-2 

PopTable, 9-10 

PushTable, 9-9 
trigger action, 9-3 
type checking 

circumventing, 12-5 



uninterpreted attributes, 10-1 

encoding and decoding, 10-4 

retrieving, 10-10 

specifying, 10-4 
user abort, 9-15 
user actions, 9-1 
User Profile 

window entries for, 2-3 

V 

virtual memory overview, 13-1 
W 

window, 2-2 

adding commands to, 4-6 

creating, 4-2 
Window interface 

Box, 4-6, 6-2, 7-8 

Clarity, 6-2 

Dims, 4-6, 6-2, 7-8 

DisplayProc , 6-3 

EnumeratelnvaiidBoxes, 6-3 

InvalidateBox (Def), 6-2 

InvalidateBox (Ex), 6-2, 6-8 

Place, 4-6, 6-2, 7-8 

Validate (Def), 6-2 

Validate (Ex), 6-2, 6-8 

ValidateTree, 6-2 
windows 

changing defaults for, 2-3 

clipping, 6-3 

control I i ng si ze of, 6- 1 0 

creation of (Ex), 4-1 1 

displaying information in, 6-1 

displaying on screen, 4-10 

overlapping mode, 2-3 

storing data with, 5-1 

tiled mode, 2-3 

validating and invalidating, 6-1 
WorkstationProfile, A-2 
writers, 3-2 

allocating, 3-5 

editing, 3-6 

expanding, 3-6 



X 

XChar, 3-1 

Xerox Character Code Standard, 3-1 
XFormat interface, 3-6 

Char, 3-9 

Character, 3-1 

CharRep, 3-1 

ClientData, 3-7 

Decimal, 3-9 

example, 3-9 

format procedures, 3-8 

FormatObject, 3-8 

FormatProc, 3-7 

Handle, 3-7 

Object (Def), 3-7 

Object (Ex), 3-9 

Reader, 3-9 

StreamObject, 3-8 

StreamProc, 3-8 

String, 3-9 

WriterObject, 3-9 
XMessage interface 

AllocateMessages (Def), 3-1 1 

Allocate Messages (Ex), 3-12, 3-13 

client module, 3-14 

definitions module, 3-1 1 

FreeMsgDomainsStorage, 16-4 

Get, 3-13 

Handle, 3-11 

implementation module, 3-1 1 
Messages, 3-12 
MessagesFromFile, 16-4 
MessagesFromReference, 16-4 
MsgDomain, 16-4 
MsgDomains, 16-4 
MsgEntry, 3-12 
MsgKey, 3-12 
Object, 3-1 1 

RegisterMessages, 3-12 
XString interface 
AppendReader, 16-8 
Byte, 3-2 
Bytes, 3-5 
ByteSequence, 3-2 
Context, 3-2 
CopyReader, 14-4 
ExpandWriter, 3-6 
First, 3-4 

FromBlock, 13-12 
FromNSString, 3-4 
FromSTRING 3-4 
InvalidNumber, 13-12 
Lop, 3-4 

NewWriterBody), 3-5 
NthCharacter , 3-4 
Overflow, 13-12 
Reader 3-2 
ReaderBody , 3-2 
ReaderFromWriter, 3-4 
ReadOnlyBytes , 3-2 
Writer, 3-5 
WriterBody, 3-5, 3-6 
WriterBodyFromNSString, 3-6 
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